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Typographical  Conventions 1 2 

Feedback 13 


Typographical  Conventions 

Before  you  start  using  this  guide,  it  is  important  to  understand  the  documentation 
conventions  used  in  it. 

The  following  kinds  of  formatting  in  the  text  identify  special  information. 


Formatting  convention  Type  of  Information  Example 


Special  Bold 

Items  you  must  select, 
such  as  menu  options, 
command  buttons,  or 
items  in  a list. 

Go  to  the  System  tab. 

Titles  of  chapters, 
sections,  and 
subsections. 

Read  the  Basic 
Administration  chapter. 

Italics 

Used  to  emphasize  the 
importance  of  a point,  to 
introduce  a term  or  to 
designate  a command 
line  placeholder,  which  is 
to  be  replaced  with  a real 
name  or  value. 

The  system  supports  the 
so  called  wildcard 
character  search. 

Monospace 

The  names  of 
commands,  files, 
directories,  and  domain 

The  license  file  is  located 
in  the 

http : //docs /common/ 

names. 

licenses  directory. 
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Pre format ted 

On-screen  computer  # ls  -al  /f  iles 

output  in  your  command-  total  14470 

line  sessions;  source 
code  in  XML,  C++,  or 
other  programming 
languages. 

Preformatted 

Bold 

What  you  type,  # cd  /root/rpms/php 

contrasted  with  on-screen 
computer  output. 

CAPITALS 

Names  of  keys  on  the  SHIFT,  CTRL,  ALT 

keyboard. 

KEY+KEY 

Key  combinations  for  CTRL+P,  ALT+F4 

which  the  user  must 

press  and  hold  down  one 

key  and  then  press 

another. 

Feedback 

If  you  have  found  a mistake  in  this  guide,  or  if  you  have  suggestions  or  ideas  on  how  to 
improve  this  guide,  please  send  your  feedback  using  the  online  form  at 
http://www.parallels.com/en/support/usersdoc/.  Please  include  in  your  report  the 
guide's  title,  chapter  and  section  titles,  and  the  fragment  of  text  in  which  you  have  found 
an  error. 


Chapter  2 


About  This  Guide 


Welcome  to  the  Parallels  H-Sphere  System  Administrator  Guide.  It  aims  at  system 
administrators  and  explains  how  to  install,  configure  and  maintain  Parallels  H-Sphere 
and  its  components. 


Chapter  3 


Pre-configuration  Wizard 


This  document  explains  how  to  shape  your  Parallels  H-Sphere  cluster,  add  boxes  and 
hosting  services  and  configure  basic  Parallels  H-Sphere  settings  after  Control  Panel 
installation. 

Welcome  to  the  H-Sphere  pre-configuration  page.  Please  shape  your  H-Sphere  cluster 
before  you  complete  H-Sphere  installation  (update). 


Configuration  File 

Import  Export  Restore  to  Default  jnj 


General  Settings 

& 

System  Domain 

Type  of  Installation 

Multi  Server 

Use  NAT  IP  mapping 

No 

Physical  Servers 

ID  Name  Host  IP  Type  Controls 


Parallels  H-Sphere  Pre-Configuration  Wizard  writes  the  cluster  configuration  into  the 
specially  formatted  config.xml  file  (download  sample  config.xml  from 
http://hsphere.parallels.com/HSdocumentation/xmls/confiq.xml).  The  Configuration  File 
form  on  the  main  page  enables  you  to: 

■ Import:  You  upload  the  prepared  XML  file  from  a local  machine  to  Parallels  H- 
Sphere  and  later  reconfigure  Parallels  H-Sphere  in  the  wizard. 

■ Export:  export  config.xml  with  your  Parallels  H-Sphere  cluster  configuration  to 
your  local  machine. 

■ Restore  to  Default:  choose  this  option  to  recreate  config.xml  and  to  restart 
configuring  Parallels  H-Sphere  cluster  in  the  wizard. 

> To  complete  the  pre-configuration  wizard: 

1 Click  the  Edit  General  Settings  icon  on  the  right  corner  of  the  General 
Settings  caption  and  fill  in  the  data  on  the  page  that  appears: 

■ System  Domain:  Specify  the  service  domain  name  here. 

■ One  Server  Installation:  check  this  box  if  you  need  a single  server  installation. 

■ Use  NAT  IP  mapping:  Check  this  box  if  you  implement  NAT  (on  page  28)  on  your 
Parallels  H-Sphere. 

Press  Submit  and  return  to  the  main  page  of  the  wizard. 
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Pre-configuration  Wizard 


2 If  you  choose  multiple  server  installation  mode,  you  will  see  the  Add 
Physical  Server  icon  on  the  right  corner  of  the  Physical  Servers  caption. 
Click  this  icon  and  proceed  to  the  form  for  adding  new  physical 
servers  and  services. 

Here  you  set  physical  server  name,  IP,  root  password  to  connect  to,  and  choose 
which  hosting  services  (CP,  Web,  mail,  DNS,  MySQL,  PostgreSQL)  will  be  installed 
there. 

Note:  At  the  moment,  VPS,  Windows,  MRTG  are  not  installed  via  Parallels  H- 
Sphere  pre-configuration  wizard. 

Choose  Use  defaults  for  this  server  to  apply  default  names  for  Parallels  H-Sphere 
logical  servers  on  this  server.  By  default,  they  are  named  webN,  mailN,  nsN,  mailN, 
mysqlN,  respectively. 

3 After  you  have  added  physical  servers  into  Parallels  H-Sphere  cluster, 
you  will  see  them  on  the  main  page  of  the  wizard. 

Click  the  Edit  icon  in  front  of  a physical  server  in  the  list  and  edit  logical  server 
parameters.  More  on  Logical  Servers  read  in  Parallels  H-Sphere  Service 
Administrator  Guide. 

4 After  you  have  done  with  Parallels  H-Sphere  configuration,  press 

Proceed  Installation  Wizard. 

5 You  will  be  taken  to  the  Confirm  Installation  page.  To  complete 
installation  via  CP  web  interface,  click  Yes,  continue 

6 On  the  page  that  appears  check  the  servers  you  want  to  be 
updated/installed  and  click  Start. 

To  see  the  update  log,  click  the  server  name  link. 

7 When  update  is  finished  and  the  light  turns  green,  click  Proceed  to 
complete  installation. 

8 On  the  page  that  appears,  click  Return  to  Admin  CP. 

You  will  be  taken  to  the  administrator  control  panel  where  you  can  maintain  your 
hosting  business. 


In  this  chapter: 

Parallels  H-Sphere  config.xml 
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Parallels  H-Sphere  config.xml 

The  config.xml  file  is  used  in  Parallels  H-Sphere  Pre-configuration  Wizard  (on  page  15). 
It  contains  Parallels  H-Sphere  cluster  configuration:  physical  servers  with  their  IPs  and 
root  passwords  to  install  Parallels  H-Sphere  to,  and  logical  servers  to  be  installed  on 
these  boxes. 

During  regular  Parallels  H-Sphere  installation,  config.xml  is  formed  in  Parallels  H- 
Sphere  Pre-Configuration  wizard  in  admin  CP  and  is  temporarily  stored  in  the 
~cpanei/ . settings  directory.  After  completing  Parallels  H-  Sphere  installation  in 
the  postinstall  mode,  installer  removes  this  file.  However,  the  postinstall  mode 
won't  continue  if  config.xml  is  missing  or  is  different  from  the  one  used  at  the 
installation. 

When  installer  runs  in  the  install  mode,  it  is  required  that  you  specify  location  of  the 
correctly  formed  config.xml.  See  Appendix  B.  Installation  Script  Options  of  Parallels  H- 
Sphere  Control  Panel  Installation  Guide. 

Elements  and  Attributes 

In  the  following  chart  xml  elements  are  marked  in  bold  and  their  attributes  - in  italics. 

physicalServers  - a list  of  Parallels  H-Sphere  physical  servers,  each  of  them 
described  as  physicalServer  with  attributes: 

■ id  - id  of  the  physical  server 

■ name  - name  of  the  physical  server 

password  - root  password  to  the  physical  server  Each  physicalServer  contains  ip  and 

logicalServers  elements: 

■ ip  - server  IP  with  attribute: 

■ type  - type  of  the  physical  server 

Element  ip  contains  such  child  elements: 

■ addr  - IP  address 

■ ipExt  - external  IP  for  NAT  mapping 

Note:  If  Parallels  H-Sphere  does  not  use  NAT,  this  child  element  is  redundant. 

■ mask -IP  mask 

■ logicalServers  - a list  of  Parallels  H-Sphere  logical  servers  each  of  them  described 
as  logicalServer  with  attributes: 

■ group  - group  of  the  logical  server 

■ id- id  of  the  logical  server 

■ name  - name  of  the  logical  server 
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Each  logicalServer  element  contains  ips  element  - a list  of  IPs,  each  of  them 
described  as  ip  with  the  following  child  elements: 

■ addr  - IP  address 

■ ipExt  - external  IP  for  NAT  mapping 

Note:  If  Parallels  H-Sphere  does  not  use  NAT  this  child  element  is  redundant. 

■ mask -IP  mask 

systemzone  - a Parallels  H-Sphere  DNS  zone 
hsversion  - a Parallels  H-Sphere  version 
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Software  Used  in  Parallels  H-Sphere 

This  chapter  lists  various  types  of  software  used  in  Parallels  H-Sphere. 

In  this  chapter: 

Integrated  Third  Party  Products 20 

Supplementary  Software 22 

Used  Libraries  and  Technologies 23 
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Integrated  Third  Party  Products 

Even  though  we  integrate  or  use  the  below  products  in  Parallels  H-Sphere,  we  do  not 
assume  any  responsibility  for  bugs  in  their  source  code.  Should  you  have  any  problems 
with  these  products,  please  contact  the  developers.  The  packages  are  listed  in  the 
alphabetical  order. 

BS  Counter  http://www.stanback.net/proqramminq/bscounter 

"This  is  a web  hit  counter/tracker  written  in  Perl,  features  include:  blocking  of  multiple 
hits  from  the  same  user,  insertion  of  commas,  text-based  or  graphical  modes,  supports 
multiple  counters  from  the  same  script,  and  tracks  users'  browsers,  operating  systems, 
locations,  top  20  referrers,  and  top  20  search  engine  keywords,  (requires  SSI  OR 
GD.pm)" 

ezmlm  http://www.ezmlm.org 

"ezmlm  is  a modern  mailing  list  manager.  Its  purpose  is  to  efficiently  send  a message  to 
a large  number  of  recipients  with  minimal  delay.  It  allows  automated  additions  and 
subtractions  from  the  subscriber  database.  In  addition,  it  may  keep  an  archive  of 
messages.  It  can  also  impose  restrictions  on  what  may  be  sent  or  retrieved  and  by 
whom.  Some  mailing  list  managers  keep  a database  of  subscriber  information  and 
tailor  the  message  specifically  for  each  subscriber,  ezmlm  sends  the  same  message  to 
all  subscribers.  This  is  much  more  efficient.  The  benefits  to  the  user  are  that  on 
average  posts  to  ezmlm  lists  reach  subscribers  much  faster  than  they  would  with  other 
mailing  list  manager." 

Form  Mail  http://www.scriptarchive.com/formmail.html 

"FormMail  is  a generic  WWW  form  to  e-mail  gateway,  which  will  parse  the  results  of 
any  form  and  send  them  to  the  specified  user.  This  script  has  many  formatting  and 
operational  options,  most  of  which  can  be  specified  through  the  form,  meaning  you 
don't  need  any  programming  knowledge  or  multiple  scripts  for  multiple  forms.  This  also 
makes  FormMail  a perfect  system-wide  solution  for  allowing  users  form-based  user 
feedback  capabilities  without  the  risks  of  allowing  freedom  of  CGI  access." 

Miva  Merchant  http://www.miva.com 

"Miva  Merchant  is  a dynamic  browser  based  storefront  development  and  management 
system  that  allows  merchants  to  create  and  administrate  multiple  online  stores  from 
anywhere  in  the  world." 

mnoGoSearch  http://www.mnoqosearch.org/ 

"mnoGoSearch  (formerly  known  as  UdmSearch)  is  a full-featured  web  search  engine 
software  for  intranet  and  internet  servers.  mnoGoSearch  software  has  a number  of 
unique  features,  which  makes  it  appropriate  for  a wide  range  of  applications  from 
search  within  your  site  to  specialized  search  systems  such  as  cooking  recipes  or 
newspaper  searches,  ftp  archive  search,  MP3  search,  news  articles  search  or  even 
national-wide  portal  search  engine." 

ModLogAn  http://jan.kneschke.de/proiects/modloqan/ 

"ModLogAn  is  a modular  logfile  analyzer  which  is  able  to  analyze  logfiles  from  15 
different  server  types." 
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MySQL  http://www.mysql.com 

"MySQL  is  the  world's  most  popular  open  source  database,  recognized  for  its  speed 
and  reliability." 

OpenSSL  http://www.openssl.org 

"The  OpenSSL  Project  is  a collaborative  effort  to  develop  a robust,  commercial-grade, 
full-featured,  and  Open  Source  toolkit  implementing  the  Secure  Sockets  Layer  (SSL 
v2/v3)  and  Transport  Layer  Security  (TLS  vl)  protocols  as  well  as  a full-strength 
general  purpose  cryptography  library  managed  by  a worldwide  community  of  volunteers 
that  use  the  Internet  to  communicate,  plan,  and  develop  the  OpenSSL  toolkit  and  its 
related  documentation."  Parallels  H-Sphere  uses  system  OpenSSL  packages.  Make 
sure  you  keep  them  updated.  OpenSSL  packages  are  upgraded  as  any  other  system 
packages. 

osCommerce  http://www.oscommerce.com 

"osCommerce  is  an  online  shop  e-commerce  solution  under  on  going  development  by 
the  open  source  community.  Its  feature  packed  out-of-the-box  installation  allows  store 
owners  to  setup,  run,  and  maintain  their  online  stores  with  minimum  effort  and  with 
absolutely  no  costs  or  license  fees  involved." 

phpBB  http://www.phpbb.com 

"phpBB  is  a high  powered,  fully  scalable,  and  highly  customisable  open-source  bulletin 
board  package.  phpBB  has  a user-friendly  interface,  simple  and  straightforward 
administration  panel,  and  helpful  FAQ.  Based  on  the  powerful  PHP  server  language 
and  your  choice  of  MySQL,  MS-SQL,  PostgreSQL  or  Access/ODBC  database  servers, 
phpBB  is  the  ideal  free  community  solution  for  all  web  sites." 

phpMyAdmin  http://www.phpmyadmin.net 

"phpMyAdmin  is  a tool  written  in  PHP  intended  to  handle  the  administration  of  MySQL 
over  the  WWW.  Currently  it  can  create  and  drop  databases,  create/drop/alter  tables, 
delete/edit/add  fields,  execute  any  SQL  statement,  manage  keys  on  fields." 

Urchin  http://www.urchin.com 

"Urchin  is  the  fastest  and  most  accurate  web  analytics  (web  statistics)  software 
available."  It  is  a commercial  product  and  is  available  for  Windows  2000,  Linux  RedHat, 
and  FreeBSD  platforms." 

WebBBS  http://www.extropia.com/scripts/bbs.html 

"eXtropia  WebBBS  allows  a user  to  post  messages  as  well  as  post  replies  to  existing 
messages.  WebBBS  keeps  track  of  which  messages  are  posts  and  which  ones  are 
replies  and  displays  them  in  a hierarchical  tree-like  fashion.  Posts  that  start  new  topics 
are  at  the  top  of  each  tree,  and  the  replies  are  shown  indented  beneath  the  original 
posts." 

WebChat  http://www.extropia.com/opensource.html 

"eXtropia  WebChat  is  a useful  application  that  allows  a number  of  people  on  the  World 
Wide  Web  to  talk  to  one  another  simultaneously.  The  ability  to  chat  on  the  Web  can  be 
a quick  way  to  hold  a virtual  meeting." 
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WebGuestbook  http://www.extropia.com/opensource.html 

eXtropia  WebGuestbook  is  "configurable  so  that  you  can  specify  what  your  guestbook 
file  looks  like  and  how  the  script-generated  responses  are  displayed.  If  configured  to  do 
so,  WebGuestbook  will  email  the  guestbook  administrator  the  text  of  new  entries  as 
well  as  add  them  to  the  guestbook.  The  script  will  also  respond  to  new  entrants  with  a 
configurable  "Thank  you"  message...  Finally,  the  application  comes  with  the  capability 
of  'four  letter  word'  filtering  for  a child-safe  guestbook.  You  can  censor  words  by  adding 
them  to  a list  of  'bad  words'." 

Webalizer  http://www.mrunix.net/webalizer/ 

"The  Webalizer  is  a fast,  free  web  server  log  file  analysis  program.  It  produces  highly 
detailed,  easily  configurable  usage  reports  in  HTML  format,  for  viewing  with  a standard 
web  browser." 


Supplementary  Software 

Apache  http://www.aoache.org/ 

The  Apache  web-server  is  used  as  the  back-end  for  all  of  PSoft  applications  running  on 
the  Unix  platform.  More  information  about  configuring  and  maintaining  Apache  is 
available  at  the  Apache  project  site. 

Postgresql  http  ://www.  oostq  resq  I . o rq/ 

While  our  products  are  designed  to  work  with  any  SQL-compliant  database  server, 
PostgreSQL  is  the  server  we  use  for  internal  development  and  testing.  Their  website 
not  only  explains  how  to  properly  set  up  this  free  database,  but  also  has  some 
information  about  SQL  in  general. 

ProFTPD  http://proftpd.net 

"Highly  configurable  GPL-licensed  FTP  server  software." 
qmail  http://www.qmail.org/top.html 

"qmail  is  a secure,  reliable,  efficient,  simple  message  transfer  agent.  It  is  designed  for 
typical  Internet-connected  UNIX  hosts.  As  of  October  2001 , qmail  is  the  second  most 
common  SMTP  server  on  the  Internet,  and  has  by  far  the  fastest  growth  of  any  SMTP 
server." 

vpopmail  http://www.inter7.com/vpopmail.html 

"vpopmail  (vchkpw)  is  a collection  of  programs  and  a library  to  automate  the  creation 
and  maintenance  of  virtual  domain  email  configurations  for  qmail  installations  using 
either  a single  UID/GID  or  any  valid  UID/GID  in  /etc/passwd  with  a home  directory. 
Features  are  provided  in  the  library  for  other  applications  which  need  to  maintain  virtual 
domain  email  accounts.  It  supports  named  or  IP-based  domains.  It  works  with  vqadmin, 
qmailadmin,  vqregister,  sqwebmail,  and  courier-imap.  It  supports  MySQL,  Sybase, 
Oracle,  LDAP,  and  file-based  (DJB  constant  database)  authentication.  It  supports 
SMTP  authentication  combined  with  the  qmail-smtp-auth  patch.  It  supports  user  quotas 
and  roaming  users  (SMTP  relay  after  POP  authentication)." 
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Used  Libraries  and  Technologies 

CGI  http://cqi.resourceindex.com 

Free  marker  http://freemarker.sourceforqe.net 

Positive  Software  uses  Freemarker  1 .5.1  template  format  for  Parallels  Pi-Sphere  and 
Parallels  SiteStudio.  Please  refer  to  this  site  for  detailed  information  about  the  format 
and  capabilities  of  Freemarker. 

HTML  http://developer.netscape.com 

Java  1.4  http://www.iavasoft.com/ 

Perl  http://www.perl.org/ 

PHP  http://www.php.net/  and  http://www.zend.com/ 

XML  http://www.oasis-open.org/ 
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Update  of  Operating  Systems 


We  do  not  recommend  major  OS  updates  that  result  in  changing  of  OSCODE  (refer  to 
Appendix  D of  Parallels  H-Sphere  Installation  Guide).  Rather,  perform  server  migration. 
You  can  have  it  done  by  Parallels  H-Sphere  support  team, 
http://www.parallels.com/support/hsphere/,  or  migrate  servers  by  yourself  using  the 
following  manuals: 

■ Moving  Mail  Service  (on  page  188) 

■ Moving  DNS  (on  page  205) 

■ Moving  MySQL  (on  page  220) 

■ Moving  CP  Server  (on  page  108) 

However,  if  you  did  update  your  OS  to  another  major  version,  delete  the  file 

/hsphere/ shared/bin/ oscode. 

In  this  chapter: 


Updating  FreeBSD  Kernel 25 

Updating  Linux 25 
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Updating  FreeBSD  Kernel 

Parallels  H-Sphere  requires  that  FreeBSD  kernel  be  compiled  with  quota  enabled. 

> To  update  kernel  on  a FreeBSD  server  in  an  Parallels  H-Sphere  cluster: 

1 Download  and  install  FreeBSD  kernel  sources. 

2 Under  root,  change  directory  to  /usr/src/sys/i386/conf , where 
the  kernel  source  is  located: 

# cd  /usr/src/sys/i386/conf 

3 In  this  directory,  you  will  have  the  default  generic  kernel 
configuration  file,  and,  if  the  custom  kernel  compilation  has  been 
performed,  a custom  kernel  configuration  file,  for  example  mykernel. 

4 Open  your  current  kernel  configuration  file  (for  example  mykernel) 
and  add  the  line: 

options  QUOTA 

Important:  We  don't  recommend  modifying  the  default  generic  file.  Instead,  copy 
its  content  to  a custom  file  (like  mykernel)  and  perform  modifications  there! 

5 Compile  and  install  the  kernel: 

# /usr/sbin/config  MYKERNEL 

# cd  compile/MYKERNEL 

# make  depend 

# make 

# make  install 

6 Reboot  FreeBSD  server  to  activate  the  new  kernel  settings. 

For  more  information,  see  generic  instructions  on  Building  and  Installing  a Custom 
Kernel  (http://www.freebsd.org/doc/en  US.IS08859-1/books/handbook/kernelconfiq- 

buildinq.html). 


Updating  Linux 

When  you  update  Linux  automatically  by  means  of  up2date  (on  page  27),  apt-get  (on 
page  27),  SWUP,  yum  (http://linux.duke.edu/proiects/vum/)  or  other  RPM  updaters,  you 
must  beforehand  exclude  some  packages  installed  with  Parallels  Pi-Sphere  from  the 
update  list: 

■ rh-postgres,  postgresql,  postgresql-server,  postgresql-libs  on  CP  and  user 
postgresql  boxes 

■ apache  and  apache-related  packages  on  Parallels  Pi-Sphere  CP,  WEB  and  MAIL 
boxes 

■ proftpd,  frontpage  and  related  packages  on  Parallels  Pi-Sphere  WEB  boxes 
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■ qmail,  vpopmail,  ezmlm,  sqwebmail  and  related  packages  on  Parallels  H-Sphere 
MAIL  boxes 

■ bind  and  related  packages  on  Parallels  H-Sphere  DNS  boxes 

■ XFree86  or  xorg-xl  1 packages  on  CP.  XFree86-deprecated-libs  (or  xorg-xl  1 - 
deprecated-libs)  with  dependences  should  be  installed.  This  is  critical  particularly  for 
Parallels  SiteStudio. 

■ MySQL-server  on  Parallels  Pi-Sphere  MAIL  and  MySQL  boxes 

Please  note  that  these  packages  are  also  to  be  removed  while  preparing  servers  to 
Parallels  Pi-Sphere  installation. 

If  you  have  accidentally  upgraded  your  RedFlat  without  excluding  these  packages,  you 
need  to  downgrade  PostgreSQL  (on  page  233). 

In  this  section: 


Linux  Up2Date 27 

Linux  Apt-Get 27 
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Linux  Up2Date 

The  up2date  utility  is  used  to  upgrade  the  Linux  Kernel  on  RedHat.  For  generic 
information  on  up2date,  please  read  Upgrading  the  Linux  Kernel  on  Red  Hat  Linux 
Systems  (http://www.redhat.com/support/resources/howto/kernel-upqrade/). 

Prior  to  updating  your  Linux  with  the  up2date  procedure,  make  sure  you  exclude 
specific  Parallels  H-Sphere  related  services  (on  page  25)  from  the  list  of  packages  to 
be  updated. 

Linux  Apt-Get 

Since  the  up2date  (on  page  27)  utility  has  become  a paid  service  by  RedHat 
(http://www.redhat.com/docs/manuals/RHNetwork/ref-quide/up2date.html),  you  may 
use  the  free  apt-get  utility  instead. 

APT-RPM  is  a port  of  Debian's  apt  tools  to  a RPM  based  distribution,  apt-get  is  an 
advanced  package  management  utility  front-end  to  easily  perform  package  installation, 
upgrading  and  removal.  Dependencies  are  automatically  handled,  so  if  you  try  to  install 
a package  that  needs  others  to  be  installed,  it  will  download  all  needed  packages  and 
install  them.  More  information  on  apt-get  can  be  found  at  http://apt.freshrpms.net/  or 
http://pt-rpm.tuxfamily.org/. 

Prior  to  updating  your  OS  packages  with  apt-get,  make  sure  you  exclude  specific 
Parallels  H-Sphere-related  services  (on  page  25)  from  the  apt-get  configuration. 

To  exclude  these  packages,  modify  the  corresponding  part  of  your 
/ etc/ apt/ apt . conf  file,  similar  to  this: 

//  Completely  ignore  the  following  packages  (not  regexp) 

//  Ignore  { }; 

Ignore  { "bind-utils";  }; 

//  Do  not  try  to  update  the  following  packages 
//  Hold  { } ; 

Hold  { 

"rh-postgres* " ; 

"postgresql* " ; 

"apache*" ; 

"proftp* " ; 

" qma i 1 * " ; 

"vpopmail* " ; 

"ezmlm*"; 

" sendmail* " ; 

"bind* " ; 

"XFree8  6 -base -fonts* " ; 

"XFree8  6-font -utils* " ; 

"XFree8  6-libs* " ; 

"XFree8  6-libs-data* " ; 

"XFree8  6-xf s* " ; 

"XFree8  6-Xvfb* " ; 

MySQL* } ; 
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Parallels  H-Sphere  supports  NAT  (Network  Address  Translation)  which  allows  you  to 
use  internal  IPs  in  your  local  area  network.  When  configuring  Parallels  H-Sphere,  use 
internal  IPs  in  all  instances,  and  Parallels  H-Sphere  will  convert  them  into  external  IPs 
for  the  DNS  settings  and  control  panel  web  interface. 

> To  enable  NA  T support  in  Parallels  H-Sphere: 

1 Log  into  Control  Panel  server  as  cpanel  user: 

1 . Log  in  as  root  first: 

$ su  - 

2.  Log  in  as  the  cpanel  user: 

# su  -1  cpanel 

2 Create  the  ips-map . xml  file  in  the 

~cpanel/ shiva/psof t_conf ig/  directory  in  the  following  format: 

<ips> 

<ip  ext =" external  ip " int =" internal  ip" /> 

</ ips> 

Example: 

<ips> 

<ip  ext=" 65.219.197.236"  int="192 . 168 . 1 . 27"/> 

<ip  ext ="65. 219. 197. 237"  int="192 . 168 . 1 . 28"/> 

<ip  ext=" 65.219.197.238"  int="192 . 168 . 1 . 29"/> 

<ip  ext=" 65.219.197.239"  int="192 . 168 . 1 . 30"/> 

<ip  ext ="65. 219. 197. 242"  int="192 . 168 . 1 . 31"/> 

<ip  ext ="65. 219. 197. 243"  int="192 . 168 . 1 . 32"/> 

<ip  ext ="65. 219. 197. 244"  int="192 . 168 . 1 . 33"/> 

</ ips> 

3 Set  the  following  record  in 

~ cpanel / shiva/ psof t_conf ig/h sphere .properties: 

IPS-XML-FILENAME  = 

/hsphere/ local /home/ cpanel/ shiva/ psoft  config/ ips-map . xml 

4 Restart  Parallels  H-Sphere  to  apply  changes.  To  do  this,  run  under 

root: 

For  Linux: 

/etc/rc.d/init.d/httpdcp  stop 
killall  -9  java 
sleep  10 

/etc/rc.d/init.d/httpdcp  start 
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For  FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
killall  -9  java 
sleep  10 

/usr/local/etc/rc.d/apachecp. sh  start 


> To  disable  NA  T support 

1 Remove  the  line  mentioned  in  step  3 above  from 

hsphere. properties. 

2 Restart  Parallels  H-Sphere. 

See  below  for  particular  cases  of  configuring  NAT  in  your  Parallels  H-Sphere  cluster. 

In  this  chapter: 


Configuring  Newly  Installed  H-Sphere  with  NAT  Support 29 

Enabling  NAT  Support  on  a Live  System 30 

Configuring  NAT  Firewall 31 

Migrating  IPs  with  NAT 31 


Configuring  Newly  Installed  H-Sphere  with 
NAT  Support 

> To  configure  newly  Installed  H-Sphere  with  NAT  support: 

1 Create  ips -map  . xml  file  and  configure  hsphere  . properties  to 
use  it  as  specified  in  the  parent  topic. 

2 In  the  E. Manager  menu,  add  your  physical  and  logical  servers  with  the 
corresponding  internal  IPs  as  described  in  Parallels  H-Sphere  Adding 
Servers  and  Services  Guide. 

3 Go  to  E. Manager ->  DNS  Manager  and  add  DNS  records  with  internal  IPs 
as  described  in  DNS  Records  section  of  Parallels  H-Sphere  Service 
Administrator  Guide. 

Note:  Internal  IPs  will  be  transformed  to  the  corresponding  external  IPs  in  DNS 
zones  configuration.  There  will  be  only  external  IPs  in  DNS  zones  configuration. 


Should  you  still  have  problems  with  resolving  your  servers  after  that,  run  DNS  Creator 
(on  page  21 1 ) using  the  following  command  under  the  cpanei  user: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz 
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Enabling  NAT  Support  on  a Live  System 

> To  add  NAT  support  to  a Parallels  H-Sphere  already  configured  with  external  IPs: 

1 Create  ips-map.xml  file  and  configure  hsphere  . properties  to 
use  it  as  specified  in  the  parent  topic. 

2 Replace  external  IPs  in  E. Manager  ->  P.Servers  and  L.Servers  with  internal 
IPs. 

Note:  These  internal  IPs  should  be  of  the  same  type  (shared,  dedicated)  as  the 
corresponding  external  IPs. 

Example:  If  there  was  a shared  64.10.10.10  external  IP,  the  corresponding 
192.128.10.10  internal  IP  should  also  be  configured  as  a shared  IP. 

In  such  a case,  there  will  be  no  need  to  recreate  DNS. 

3 Replace  external  IPs  in  E. Manager ->  DNS  Manager  with  the  corresponding 
internal  IPs. 

Note:  Internal  IPs  will  be  transformed  to  the  corresponding  external  IPs  in  DNS 
zones  configuration.  There  will  be  only  external  IPs  in  DNS  zones  configuration. 


Should  you  still  have  problems  with  resolving  your  servers  after  that,  run  DNS  Creator 
(on  page  21 1 ) using  the  following  command  under  the  cpanei  user: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz 
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Configuring  NAT  Firewall 

Some  software  (osCommerce,  phpBB,  and  Parallels  SiteStudio)  connects  to  resources 
by  hostname  (web . example . com,  mysqi . example . com).  Since  hostnames  resolve 
to  external  IPs,  you  need  to  configure  your  NAT  firewall  so  that  your  physical  servers 
(web . example . com,  mysqi . example . com)  can  address  themselves  and  each  other 
both  by  external  and  internal  IPs. 

Alternatively,  if  you  have  RedHat  Linux  running  on  all  servers,  you  can  add  the 
following  rule  to  the  iptables  for  each  IP  pair  on  every  single  box: 

iptables  -t  nat  -A  OUTPUT  -p  tcp  -d  <external>  -j  DNAT  --to  <internal> 

For  example: 

iptables  -t  nat  -A  OUTPUT  -p  tcp  -d  65.219.197.236  -j  DNAT  --to 
192.168.1.27  iptables  -t  nat  -A  OUTPUT  -p  tcp  -d  65.219.197.237  -j  DNAT 
--to  192.168.1.28  iptables  -t  nat  -A  OUTPUT  -p  tcp  -d  65.219.197.238  -j 
DNAT  --to  192.168.1.29  iptables  -t  nat  -A  OUTPUT  -p  tcp  -d 
65.219.197.239  -j  DNAT  — to  192.168.1.30  iptables  -t  nat  -A  OUTPUT  -p 
tcp  -d  65.219.197.242  -j  DNAT  --to  192.168.1.31  iptables  -t  nat  -A 
OUTPUT  -p  tcp  -d  65.219.197.243  -j  DNAT  --to  192.168.1.32  iptables  -t 
nat  -A  OUTPUT  -p  tcp  -d  65.219.197.244  -j  DNAT  — to  192.168.1.33 


Migrating  IPs  with  NAT 


For  IP  migration  with  NAT,  see  the  section  on  changing  IPs  (on  page  40). 
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Server  Time  Synchronization 


This  document  explains  how  to  automate  adjusting  your  servers'  time  through  Network 
Time  Protocol  (NTP).  Server  time  synchronization  prevents  various  errors  that  you  are 
likely  to  run  into  unless  your  servers'  time  is  correct.  Automation  of  server  time 
synchronization  is  implemented  through  setting  up  crontab  task  for  your  NTP  client. 

> To  automate  adjustment  of  your  servers'  time  through  NTP: 

1 Make  sure  you  have  got  an  NTP  client  software  installed  on  your 
server(s).  If  not,  download  it  from  www.ntp.org. 

2 Choose  time  server(s)  (on  page  32)  and  add  it  to  your  NTP  client 
configuration. 

3 Log  into  your  servers  as  root  and  use  the  crontab  -e  command  to 
add  an  NTP  cron  task. 

In  the  following  example  your  server  time  is  checked  with  a time 
server  every  4 hours: 

# date  syncronization 

0 */4  * * * /usr/sbin/ntpdate  ntpsl- { 0 , 1 , 2 } . uni-erlangen . de 


In  this  chapter: 
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NTP  Time  Servers 


The  following  links  will  take  you  to  the  lists  of  time  server  hosts  to  choose  from. 

■ Public  NTP  Pool  Time  Servers  (http://ntp.isc.org/bin/view/Servers/NTPPoolServers) 

■ Public  NTP  Secondary  (stratum  2)  Time  Servers 
(http://ntp.isc.org/bin/view/Servers/StratumTwoTimeServers) 

■ Public  NTP  Primary  (stratum  1)  Time  Servers 
(http://ntp.isc.org/bin/view/Servers/StratumOneTimeServers) 

To  find  the  time  servers  that  best  suit  your  server  location  and  other  requirements,  go 
to  http://ntp.isc.org/bin/view/Servers/WebSearch 
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Cron  Scripts 


Parallels  H-Sphere  uses  cron  utility  on  Unix  servers  to  schedule  the  automatic  launch 
of  the  Parallels  H-Sphere  scripts  for  updating  system  information,  collecting  traffic, 
analyzing  logs,  etc. 

To  view  the  list  of  cron  jobs  on  a server,  type  the  following  command  under  root  on  this 
server: 

# crontab  -1 

Crontab  enables  you  to  set  the  sequence  and  regularity  of  launching  the  scripts.  To  edit 
crontab  list,  type  the  following  command  under  root: 

# crontab  -u  root  -e 

For  more  details  on  editing  cron,  read  man  5 crontab. 

Below  see  the  list  of  cron  jobs  for  Parallels  H-Sphere  logical  servers. 
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Control  Panel  Server  Crons 33 

Web  Server  Crons 34 

DNS  Server  Cron 34 

Mail  Server  Crons 35 

PostgreSQL/MySQL  Server 35 


Control  Panel  Server  Crons 


30  5 * * * su  -1  cpanel  -c  "java  psoft.hsphere.TrafficLoader" 
0 4 * * * su  -1  cpanel  -c  "java  psoft .hsphere .UsageLoader" 


Here, 

■ Traf  f icLoader  is  the  Parallels  H-Sphere  Java  utility  to  collect  the  traffic  statistics 
from  the  traffic  logs  to  the  Parallels  H-Sphere  database. 

■ UsageLoader  is  the  Parallels  H-Sphere  Java  utility  to  collect  disk  usage  statistics 
into  the  Parallels  H-Sphere  database. 
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Web  Server  Crons 

*/5  * * * * nice  -15  /hsphere/shared/scripts/cron/apache-restart . pi 

20  */2  * * * nice  -15  /hsphere/shared/scripts/cron/analyze . pi 

*/5  * * * * /hsphere/shared/scripts/cron/ftp-restart.pl 

0 2 * * * nice  -15  /hsphere/shared/scripts/cron/cron_rotate . pi 

0 3 * * * nice  -15  /hsphere/shared/scripts/cron/f tp_anlz . pi 

0 4 * * * nice  -15  /hsphere/shared/scripts/cron/f tp_anlz_user . pi 

0 6 * * * nice  -15  /hsphere/shared/scripts/cron/mnogosearch_index . pi 

Here, 

■ apache-restart . pi  is  the  Parallels  H-Sphere  script  to  restart  Apache  web 
server;  Apache  is  restarted  only  if  the  /hsphere/shared/scripts/apache- 
reconfig  script  has  been  launched  by  Parallels  H-Sphere  beforehand. 

■ anaiyze.pl  is  the  Parallels  H-Sphere  Perl  script  to  calculate  the  traffic. 

■ ftp-restart  .pi  is  the  Parallels  H-Sphere  script  to  restart  FTP. 

■ cron_rotate.pl  is  the  Parallels  H-Sphere  Perl  script  to  collect  and  rotate  user 
traffic  for  external  traffic  calculation  programs  like  Modlogan,  Webalizer  or  Urchin. 

■ ftp_aniz.pl  is  the  Parallels  H-Sphere  script  to  analyze  virtual  FTP  traffic  and 
write  it  to  the  Parallels  H-Sphere  statistics  directory. 

■ ftp_aniz_user.pl  is  the  Parallels  H-Sphere  script  to  analyze  FTP  traffic  and 
write  it  to  the  Parallels  H-Sphere  statistics  directory. 

■ mnogosearch_index . pi  is  the  Parallels  H-Sphere  Perl  script  to  update  the 
MnoGoSearch  index. 


DNS  Server  Cron 

*/l  * * * * [ "x'ps  -ax  Igrep  -v  greplgrep  named'"  = "x"  ] && 
/hsphere/shared/ scripts/cron/dns_check 

dns_check  is  the  Parallels  H-Sphere  shell  script  to  check  DNS  settings. 
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Mail  Server  Crons 

30  * * * * /hsphere/local/var/vpopmail/bin/clearopensmtp 
*/ 20  * * * * /hsphere/local/sqwebmail/share/sqwebmail/cleancache . pi 
0 3 * * * nice  -15  /hsphere/shared/scripts/cron/mail_overlimit . pi 
30  3 * * * nice  -15  /hsphere/shared/scripts/cron/mail_anlz . sh 
0 * * * * /hsphere/shared/bin/freshclam  --quiet 

Here, 

■ clear opensmtp  is  the  vpopmail  utility  to  clean  smtp  logs. 

■ cleancache . pi  is  the  sqwebmail  utility  to  clean  the  webmail  cache. 

■ mail  overlimit . pi  is  the  Parallels  H-Sphere  Perl  script  to  check  overlimits  on 
the  mail  boxes. 

■ maii  aniz . sh  is  the  Parallels  H-Sphere  Perl  script  to  analyze  qmail  traffic  and 
place  it  into  the  H-Shere  statistics  directory. 

■ f reshclam  is  the  script  to  update  ClamAV  virus  patterns. 


PostgreSQL/MySQL  Server 

10  3 * * * nice  -15  /hsphere/shared/scripts/cron/db_usage . pi 

db_usage.pl  is  the  Parallels  H-Sphere  Perl  script  to  collect  statistics  on  the  database 
usage  for  PostgreSQL  and  MySQL  servers. 
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Traffic  Calculation 

This  chapter  dwells  specifically  on  the  issues  of  traffic  logs  and  traffic  calculation. 

In  this  chapter: 

Checking  Traffic  via  Parallels  H-Sphere  Control  Panel 37 

Checking  Traffic  on  Physical  Servers 37 

Processing  Traffic  by  Crons 38 

Parsing  T raffic  by  T rafficLoader 39 
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Checking  Traffic  via  Parallels  H-Sphere 
Control  Panel 

> To  check  traffic  using  the  control  panel: 

1 Log  into  your  administrator  control  panel. 

2 Check  the  traffic  by  going  to  Reports  ->  Transfer  Traffic  Report. 

Read  more  in  Reports  section  of  Parallels  H-Sphere  Service  Administrator  Guide. 


Checking  Traffic  on  Physical  Servers 

Web,  FTP  and  mail  logs  are  located  in  the  /hsphere/iocai/var/statistic 
directory  of  the  corresponding  physical  server. 

Log  are  named  as  follows: 

■ dd.mm.YYYY.txt  - web  logs 

■ dd.mm.YYYY.gst.txt  - ftp  logs 

■ dd . mm . YYYY  . f tp  . txt  - virtual  ftp  logs 

■ dd . mm . YYYY  . qml  - mail  logs 

where  dd.mm.  yyyy  is  the  timestamp  of  log  file  creation  date. 

Here,  mail  logs  are  generated  by  the  qmail  server,  and  ftp  logs  by  the  proftpd  utility. 
Log  files  contain  specially-formatted  information  tabulated  as  follows: 

| name | xFer ( kB) | Hits_All | Hits_HTML | 

Here,  name  is  the  domain  name,  xFer  is  total  traffic  in  kilobytes. 

Processed  traffic  files  are  moved  to  the  /hsphere/local/var/statistic/loaded 
directory  as  . gz  archives. 


Refer  to  section  Winbox  Traffic  Calculation  (on  page  306)  to  find  out  how  traffic  data  on 
Winbox  is  read  using  XMLs. 
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Processing  Traffic  by  Crons 
HTTP  traffic 

Please  refer  to  Web  Traffic  Calculation  (on  page  133)  for  details. 

User  FTP  traffic 

Cron  runs  the  /hsphere/ shared/ scripts/ cron/ ftp  anlz  user  .pi  script  On 
everyday  basis  for  collecting  user  FTP  traffic. 

ftp  anlz  user  . pi  parses  the  /hsphere/local/var/proftpd/xferlog  FTP 

log  file  and  writes  FTP  traffic  statistics  into  the  timestamp-named 

/hsphere /local/var/ statistic/ dd .mm.  YYYY  . gst . txt  Statistics  files. 

Virtual  FTP  traffic 


Cron  runs  the  /hsphere/ shared/ scripts/ cron/ ftp  anlz . pi  script  on  everyday 
basis  for  collecting  virtual  FTP  traffic. 

ftp_aniz.pl  parses  the 

/hsphere/local/var/proftpd/logs/ {vhost_id}  . ftp.  log  logs  files  for  each 
virtual  FTP  account  and  writes  traffic  statistics  into  the  timestamp-named 

/hsphere /local/var/ statistic/ dd  .mm.  YYYY  . f tp  . txt  Statistics  files. 

Mail  traffic 


Cron  runs  the  /hsphere/ scripts/ cron/maii_aniz . pi  script  on  everyday  basis 
to  collect  mail  traffic.  The  script  analyzes  the  /var/iog/maiiiog  Qmail  log  file  and 
collects  mail  statistics  into  the  specially  formatted  dd . mm . yyyy  . qmi . txt  files  in  the 
Parallels  Pi-Sphere  statistics  directory  (/hsphere/iocai/var/statistic). 
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Parsing  Traffic  by  TrafficLoader 

1 TrafficLoader  Parallels  H-Sphere  Java  class  is  in  charge  of  parsing 
the  server  traffic.  That's  how  it  is  launched  by  cron: 

30  5 * * * su  -1  cpanel  -c  'java  psoft . hsphere . TrafficLoader ' 

TrafficLoader  processes  Web,  mail,  FTP  and  virtual  FTP  traffic  in  the  formatted 
statistics  files  located  in  the  /hsphere/iocai/var/statistic  directory  and  inserts 
these  lines  into  the  translog  table  of  the  Parallels  H-Sphere  system  database. 

T rafficLoader  also  calls  the  /hsphere/ shared/ scripts/xf er_cat  .pi  script  to 
move  the  already  loaded  statistics  files  to  the 

/hsphere/local/var/statistic/loaded  directory  as  . txt.gz  archives. 
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IP  Migration  (Changing  IPs) 


This  chapter  explains  how  to  change  IPs  on  Unix/Linux  servers  for  Parallels  H-Sphere 
2.4.x  and  up.  If  you  have  an  older  version,  please  get  updated  first. 
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Changing  IPs  on  Systems  Without  NAT 

Parallels  H-Sphere  IP  migration  is  performed  by  means  of  Java  IP  Migrator  called  by 
the  IPMIGR  wrapper  available  for  download  from  http://download.hsphere.parallels.com 
website.  IP  Migrator  will: 

■ change  Parallels  H-Sphere  physical,  logical,  and  system  IPs 

■ update  IPs  in  Parallels  H-Sphere  database 

■ change  IPs  in  the  system  files  except  network  startup  configuration 

■ update  IP-dependent  resources  such  as  apache,  FTP  and  DNS 

IP  Migrator  does  not  migrate  NIC  system  files  to  avoid  potential  problems  with  server 
inaccessibility.  These  files  must  be  migrated  manually  by  the  local  administrator. 

IP  Migrator  does  no  modify  reverse  DNS  configuration  because  Parallels  H-Sphere 
doesn't  manage  reverse  DNS.  For  information  on  reverse  DNS  configuration,  you  may 
refer  to  www.tldp.orq/HOWTO/DNS-HOWTO-5.html#ss5.3 


In  this  section: 


IP  Migration  Pre-requisites 41 

IP  Migration  Map  File 42 

IP  Migration  Step  by  Step 44 
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IP  Migration  Pre-requisites 

Before  you  begin  IP  migration,  do  the  following  changes,  and  do  not  forget  to  undo 
them  after  the  migration: 

1 Add  the  following  line  to  the  very  beginning  of  the  /hsphere/shared/scripts/apache- 
reconfig  script.  This  will  prevent  Apache  from  restarting  gracefully  after  posting  each 
web  site  configuration: 

exit  0 

2 (Skip  this  step  for  IP  Migrator  0.3  and  up,  and  for  Parallels  H-Sphere  2.4.3 
Patch  5.  If  you  do  the  migration  under  FreeBSD,  and  IP  to  be  bound  is  the 
same  as  main  IP,  you  need  to  perform  this  step  notwithstanding  the  IP 
Migrator  version.  Otherwise  you  system  is  at  risk  of  get  crashed.) 

Add  the  following  line  to  the  very  beginning  of  the 

/hsphere/ shared/ scripts/ ip-shared  script.  This  will  protect  the  main 
Parallels  H-Sphere  IP. 

exit  0 


After  that,  replace  the  IP  on  the  main  network  interface  to  the  new  IP  for  all  boxes,  and 
set  up  the  old  IP  as  an  alias  for  the  new  one. 

Example: 

ethO  Link  encap : Ethernet  HWaddr  00 : D2 : B5 : A1 : 07 : 12 

inet  addr : [New  IP]  Beast: [New  Broadcast]  Mask[New  NetMask] : 

UP  BROADCAST  RUNNING  MULTICAST  MTU: 1500  Metric :1 
RX  packets : 269050319  errors : 0 dropped: 0 overruns :0  frame: 11 
TX  packets : 336024701  errors : 0 dropped: 0 overruns: 19  carrier :0 
collisions:0  txqueuelen : 100 
Interrupt:21  Base  address : 0x4000 

ethO : 0 Link  encap : Ethernet  HWaddr  00 : D2 : B5 : A1 : 07 : 12 

inet  addr: [Old  IP]  Beast: [Old  Broadcast]  Mask: [Old  NetMask] 

UP  BROADCAST  RUNNING  MULTICAST  MTU: 1500  Metric :1 
Interrupt:21  Base  address : 0x4000 

Important:  If  IP  migration  is  performed  whsphere- 

apache.html#script_restarting_apache  within  one  datacenter,  make  sure  that  your 
servers  can  be  accessed  from  the  Internet  at  both  old  and  new  IPs.  If  you  change  to 
IPs  outside  your  datacenter,  it  would  take  a downtime  before  you  make  your  servers 
available  on  new  IPs. 
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IP  Migration  Map  File 

Before  you  start  IP  migration,  you  may  manually  create  an  IP  migration  map  file  in  the 
cpanel  user  home  directory  -cpanel/.  The  file  contains  the  list  of  old  IPs  to  be 
migrated  to  new  IPs.  It  can  be  either  an  XML  file  (on  page  43),  or  a plain  text  file  of  the 
following  format: 

I P_OLDl  IP_NEW1  [MASK_NEW1] 

I P_OLD2  IP_NEW2  [MASK_NEW2 ] 

IPjOLDn  IP_NEWn  [MASK_NEWn] 

Specify  the  mask  in  the  third  column  only  if  it  differs  from  the  default  mask 
(255.255.255.0)  for  this  particular  IP.  Otherwise,  omit  it. 


This  manually  created  IP  migration  map  file  will  be  used  by  the  Parallels  H-Sphere  IP 
migrator  (on  page  45)  script.  IP  migrator  is  able  to  convert  plain  text  map  files  into  XML 
and  provides  interface  to  automatically  create  a ready-to-use  map  XML  file  according  to 
the  admin's  choice. 


Important:  IP  migration  map  file  must  have  the  cpanel : cpanel  ownership!  Either 
create  it  under  the  cpanel  user  (on  page  65),  or  run  under  root: 

chown  cpanel : cpanel  ipmap.xml 


In  this  section: 


IP  Migration  Map  XML  File 
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IP  Migration  Map  XML  File 

IP  migration  map  XML  file  contains  the  set  of  IPs  to  be  replaced  with  new  ones.  This 
file  must  be  created  in  the  cpanel  user  home  directory  -cpanel/  and  must  have 

cpanel : cpanel  ownership. 

This  document  explains  alternative  ways  of  creating  ipmigration.xml. 

Creating  ipmigration.xml  Manually 

IP  migration  XML  has  the  following  format: 

<?xml  version=" 1 . 0 " ?> 

< ! DOCTYPE  ips  [ 

<! ELEMENT  ips  (ip+)> 

<! ELEMENT  ip  (#PCDATA)> 

< ! ATTLIST  ip  name  CDATA  #REQUIRED> 

< ! ATTLIST  ip  new_ip  CDATA  #REQUIRED> 

< ! ATTLIST  ip  new_mask  CDATA  " [New_NetMask] "> 

] > 

<ips> 

<!--  Delete  the  lines  with  IPs  you  don't  want  to  migrate!  --> 

<ip  name="  [01d__IPl  ] " new  ip="  [New__IPl]  "/> 

<ip  name=" [01d_IP2 ] " new  ip=" [New_IP2] "/> 

<ip  name=" [Old  IP3]"  new  ip=" [New_IP3] "/> 

<ip  name=" [01d_IP4 ] " new  ip=" [New_IP4 ] " new  mask=" [New  NetMask2]"/> 
</ips> 

In  the  DTD  header  of  the  XML  file,  specify  what  attributes  will  be  provided  with  each  IP. 
Set  [New_NetMask]  to  the  default  netmask  value  for  new  IPs: 

<! ATTLIST  ip  new_mask  CDATA  "255 . 255 . 255 . 0"> 

To  set  a different  netmask  for  a particular  IP,  set  the  new_mask  attribute  in  the  ip  tag 
for  that  IP.  Otherwise,  omit  the  new_mask  attribute. 

In  the  <ips>  . . . </ips>  block,  list  all  old-new  IP  pairs,  including  users'  dedicated 
IPs.  If  you  have  specified  the  common  netmask  in  the  DTD  header,  you  do  not  need  to 
set  it  in  the  definition  line  for  each  individual  IP: 

<ip  name=" [Old  IP] " new  ip=" [New_IP] " /> 

If  you  have  set  new  mask  in  the  DTD  header  to  #REQUIRED,  you  need  to  specify  the 
netmask  parameter  for  each  IP: 

<ip  name=" [Old  IP]"  new  ip=" [New  IP]"  new  mask=" [New  NetMask]"/> 

Creating  ipmigration.xml  by  Parallels  H-Sphere  IP 
Migrator 

IP  Migrator  allows  you  to  create  ipmigration.xml  automatically  when  you  perform 
migration  by  running  the  IP  migrator  script  (on  page  45). 
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IP  Migration  Step  by  Step 

The  steps  below  are  performed  on  the  server  with  the  Control  Panel  installed. 

1 Log  into  the  CP  server  as  root: 

# su  - 

2 Download  IP  Migrator: 

# wget  http://download.hsphere.parallels.com/shiv/IPMIGR- 
0.9.1. tgz 

3 Untar  the  archive: 

# tar  -zxf  IPMIGR-x . x . tgz 
where  x.x  is  IP  Migrator  version. 

4 Enter  the  IP  Migrator  directory: 

# cd  IPMIGR 

5 Install  the  IP  Migrator: 

# make  install 

This  will  install  the  following  files: 

■ ''-cpanel/ ipmigrator  - IP  migrator  itself 

■ ~cpanei/iPMigratorFast  .jar  - makes  Parallels  H-Sphere  related 
changes:  in  the  system  database,  configs,  etc. 

■ ~cpanei/ shiva/ ipm/ ipmigr  - makes  changes  in  service  config  files  on 
Parallels  H-Sphere  servers 

6 Stop  Parallels  H-Sphere  (on  page  54) 

7 Back  up  Parallels  H-Sphere  system  database  (on  page  432) 

8 Log  in  as  the  cpanel  user  (on  page  65) 

9 Run  the  IP  Migrator  script  (on  page  45).  The  IP  Migrator  script  is 
located  in  the  cpanel  home  directory. 

10  Start  Parallels  H-Sphere  (on  page  54) 

11  Remove  the  following  line  from 

/hsphere/shared/scripts/apache-reconfig  and  from 
/hsphere/ shared/ scripts/ ip- shared: 

exit  0 

12  If  the  IPs  have  been  migrated  successfully  and  all  IP-dependent 
services  seem  to  work  fine,  finish  the  migration  by  removing  the  old 
IPs.  To  remove  the  old  IPs,  run: 

./ipmigrator  — clear-old- ips  --  xml =<ipm_xml> 


Where  <ipm_xml>  is  the  IP  migration  map  XML  file  that  you  used  for  the  migration. 
Example: 

./ipmigrator  --clear-old-ips  --xml=ipml . xml 
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Parallels  H-Sphere  version  is:  2.4.3.503.  The  new 
IPMigratorFast  will  be  used. 

Removing  old  IPs 
Done 

13  Run  the  following  Java  tool  to  regenerate  all  config.xml  files  on  all 
servers  according  to  the  Parallels  H-Sphere  system  database: 

j ava  psoft.hsinst. boxes. ClusterPreparer 


In  this  section: 
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Running  the  IP  Migrator  Script 

This  instruction  guides  you  step-by-step  through  running  the  IP  Migrator  script  which  is 
the  main  part  of  the  IP  migration  (on  page  40)  procedure.  The  IP  Migrator  script  is 
located  in  the  cpanel  home  directory.  To  start  running  the  script,  type: 

. /ipmigrator 


Carefully  follow  the  error  notifications.  You  may  also  find  more  detailed  information  on 
the  migration  process  in  the  -cpanei/Migration . log  and  the 

/ var/  log/hsphere/hsphere  .log  files. 


IP  migrator  will  guide  you  through  the  following  steps.  Let's  take  an  example  with  the 
following  physical  servers: 


Server  ID 


Server  Name 


Server  IP  Address 


22 

ns4 . vps . psof t 

192 .168 .112.234 

21 

ns3 . vps . psof t 

192 .168 .114.233 

20 

cp . vps . psof t 

192 .168 .112.232 

In  this  section: 
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Step  1.  Changing  Physical  Server  IPs 

Enter  ID  of  the  server  you  want  to  change  IPs  for. 
Type  [q]  to  quit  the  script  or  [-]  to  skip  this  step. 

[IPMigrator] : 21 

Enter  new  192.168.1 12.233  IP  for  ns3.vps.psoft: 

[IPMigrator]:  192.168.112.233 
Uploading  front-end  migration  scripts... 
===  192.168.112.233  === 


Step  2.  Preparing  IP  Migration  Map 

On  this  step,  create  or  edit  IP  migration  map.  If  you  quit  right  after  editing  or  creating 
the  file,  your  changes  will  not  be  lost. 

Enter: 

■ [ f ] to  use  existing  IP  migration  map  XML  file  (on  page  43) 

■ [ l ] to  transform  existing  IP  map  plain  text  file  with  whitespace  separated  values  to 
XML  format 

■ [c]  to  create  a new  IP  map  XML  structured  file  based  on  your  Parallels  H-Sphere 
boxe(s)  configuration 

■ [e]  to  set  the  editor  to  open  the  IP  map  file  with.  By  default,  it  is  [vi] 

■ [b]  to  go  back  to  the  previous  step 

■ [q]  to  quit  the  script 

By  default,  script  looks  for  the  file  in  the  current  directory.  Specify  the  full  path  if  you 
have  it  in  a different  location. 

Examples: 

[IPMigrator] : f 

Current  directory  is:  /hsphere/local/home/cpanel/ 

Enter  the  filename:  ipml.xml 

[ IPMigrator] : 1 

Current  directory  is:  /hsphere/local/home/cpanel/ 

Enter  the  plain  (text  file  with  whitespace  separated  values)  IP  map 
file  name  to  load  from:  ipml.txt 

Current  directory  is:  /hsphere/local/home/cpanel/ 

Enter  the  new  (XML  structured)  IP  map  file  name  to  load  into:  ipml.xml 
[IPMigrator] : c 

Current  directory  is:  /hsphere/local/home/cpanel/ 

Enter  the  plain  IP  map  new  file  name  be  generated:  ipm2.txt 
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Step  3.  Reposting  configs 


Important!  If  you  are  migrating  IPs  of  your  webserver(s),  check  the  corresponding 
logical  server(s). 


On  this  step,  check  logical  web  servers  you  want  to  repost  apache  configurations  for. 
Say,  you  have  the  following  logical  web  servers: 


ID 

Server  Name 

Server  Role 

Process 

27 

web2 . vps . psoft 

web  servers 

No 

24 

web . vps . psoft 

web  servers 

No 

31 

web3 . vps . psoft 

web  servers 

No 

Enter: 

■ [ server_id]  ID  of  the  server  you  want  to  add  to  the  migration  list 

■ [-]  to  start  the  migration 

■ [b]  to  go  back  to  the  previous  step 

[q]  to  quit  the  script  Example: 

[IPMigrator] : 31 


Step  4.  Final  Check 


Warning!  The  rest  of  the  steps  imply  physical  changes.  If  you  do  not  want  the  migration 
to  continue,  make  sure  to  quit  the  script  now. 


On  this  step  check  which  files  on  your  servers  would  be  changed,  except  for  Parallels 
H-Sphere  dependent  resources. 

Enter: 

■ [ server_id]  ID  of  the  server  you  want  to  preview  the  changes  for 

■ [-]  to  continue 

■ [r]  to  roll  the  changes  back 

■ [b]  to  go  back  to  the  previous  step 

■ [q]  to  quit  the  script 

[IPMigrator] : 320 

Line  8:  CP_HOST  = 192.168.112.232 
Line  119:  PATH_SITE_STUDIO  = 

http://192.168. 112. 232:8080/ studio/ servlet /psoft .masonry . Builder 

File  /hsphere/local/home/ cpanel/ shiva/psof t_conf ig/hsphere .properties 
IP  entries:  2 
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Line  2:  1 92 . 1 68 . 1 12 . 232 : allow, RELAYCLIENT=" " 
Line  3:  1 92 . 1 68 . 1 12 . 233 : allow, RELAYCLIENT=" " 
Line  4:  1 92 . 1 68 . 112 . 234 : allow, RELAYCLIENT=" " 

File  /hsphere/local/var/vpopmail/etc/tcp. smtp 
IP  entries:  3 


Line  6:  $cf gServers [ 1 ] [ ' host ' ] = '192.168.112.233'; 

File  /hsphere/ shared/ apache /htdocs/phpMyAdmin/ conf ig . inc . php 
IP  entries:  1 


Line  21:  <A  href="http : / /I 92 . 1 68 . 1 12 . 232/cgi-bin/sqwebmail">SQWebMail  - 
mail  client</A>XBR> 

Line  22:  <A  href="http :/ /I 92 . 1 68 . 1 12 . 232/horde/index . php">IMP  - mail 
client</AXBR> 

Line  23:  <A 

href =" http : / /192 . 168 . 112 . 232 : 8080/psoft/ servlet /psoft . hsphere . CP? act ion 
=change  mbox_password">Change  your  POP3  password</AXBR> 

File  /hsphere/ shared/ apache/htdocs/ index . html 
IP  entries:  3 


Line  288:  <VirtualHost  192 . 168 . 112 . 232> 

Line  296:  ServerName  192.168.112.232 
Line  310:  #<VirtualHost  #192 . 168 . 112 . 232> 
Line  318:  tServerName  #192.168.112.232 

File  /hsphere /local/ conf ig/httpd/httpd .conf 
IP  entries:  4 


Line  3:  Bind  192.168.112.232 

File  /hsphere /local/ conf ig/ f tpd/ prof tpd .conf 
IP  entries:  1 


Line  4:  192.168.112.236; 
Line  5:  192.168.112.232;  }; 

File  /etc/named . conf 
IP  entries:  2 


Line  1:  192.168.112.236  255.255.255.0 
Line  2:  192.168.112.232  255.255.255.0 
Line  3:  192.168.112.232  255.255.255.0 

File  /hsphere/local/network/ips 
IP  entries:  3 


Line  2:  192.168.112.236  vpsl. psoft 
Line  3:  192.168.112.232  vpsl. psoft 
Line  4:  192.168.112.232  cp.vps. psoft 
Line  5:  192.168.112.232  cp.vps. psoft 
Line  6:  192.168.112.236  cp.vps. psoft 
Line  7:  192.168.112.232  cp.vps. psoft 
Line  9:  192.168.112.232  cp.vps. psoft 
Line  10:  192.168.112.236  cp.vps. psoft 

File  /etc/hosts 
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IP  entries:  8 


Line  1 
Line  2 
Line  3 
Line  4 


nameserver 

nameserver 

nameserver 

nameserver 


192 .168 .112.232 
192.168.112.236 

192 .168 .112.233 

192.168.112.234 


File  /etc/resolv . conf 
IP  entries:  4 


If  you  want  to  proceed  the  IP  changes  in  the  files  listed  abowe  use  the 
following  command: 

/hsphere/shared/scripts/ipm/ipmigr  --action=process  --scode=mncw  < 
ipmigration . xml 

If  you  don't  want  to  proceed  any  changes  you  can  clear  the  temporary 
files  by  running  the  following  command: 

/hsphere/shared/scripts/ipm/ipmigr  --action=clear  --scode=mncw  < 
ipmigration . xml 

Step  5.  Changing  System  and  Logical  IPs 

The  process  will  take  a while  to  complete. 

Example: 

Changing  IPs  in: 


Parallels  H-Sphere  Database...  Done 


Server  configuration  files...  Done 


Changing  IP  Dependent  resources...  Done 


Fixing  service  zones 
Done 


Fixing  Custom  records 
Done 


Reposting  SSL  CP  VHost  configs 
Done 


Press  Enter  to  continue: 

When  you  have  finished  running  the  IP  Migrator  script,  go  on  with  the  IP  migration  (on 
page  40). 
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Changing  External  IPs  on  Systems  with 
NAT 


This  section  explains  how  to  change  your  external  IPs  on  a system  using  NAT  (see 
details  here  (on  page  28)).  You  may  need  to  follow  this  instruction  when  you  move  to  a 
different  location  and  would  like  to  preserve  your  internal  IP  settings. 

1 Change  IPs  in  ~cpanel/shiva/psoft_conf ig/ips-map . xml  and 
~cpanel/ shiva/ psof t_conf ig/h sphere .properties 

2 Change  IPs  in  Parallels  SiteStudio  configs 

/hsphere / shared/ Si teStudio/pso ft_conf ig/ * . You  can  use  a 

simple  script: 

# ! /bin/ sh 

if  [ $#  = 0 ] ; then 

echo  $"Usage:  changeip.sh  OldIP  NewIP" 
exit  1 
fi 

for  i in  /hsphere/shared/SiteStudio/psoft  config/* . properties 
do 

echo  "Processing  $i"; 
echo  ",s/$l/$2/g 
wq"  | ed  $i 
done 

3 Change  external  IPs  in  httpd.conf  on  the  web  box. 

4 Restart  Parallels  H-Sphere  (on  page  54) 

5 Restart  Apache  (on  page  375) 

6 Log  in  as  the  cpanel  user  (on  page  65)  and  recreate  zones  with  the 
dns  creator: 

java  psof t. hsphere. tools. DNSCreator  -m  db  -dz 
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Changing  Internal  IPs  on  Systems  With 
NAT 

> To  change  from  one  set  of  internal  IPs  to  another: 

1 Change  the  IPs  in  -cpanel / Shiva/ psof t_conf ig/ ips -map . xml. 

2 Change  your  internal  IPs  by  following  the  instruction  on  Changing  IPs 
on  Systems  Without  NAT  (on  page  40). 


Configuring  Parallels  H-Sphere  to  Work 
on  Two  Sets  of  IPs 


If  you  would  like  to  ensure  smooth  change  of  IPs  and  have  everything  duplicated  on  the 
old  and  new  sets  of  IPs  before  making  the  switch,  you  need  to  do  the  following: 

On  the  Web  box: 

1 Before  the  IP  migration  you  need  to  copy  the 

/hsphere/ local/ config/httpd/ sites  directory  to 
/hsphere/ local/ config/httpd/ sites,  old  to  preserve  your  old 
client's  apache  configs. 

2 Goto  /hsphere  / 1 ocal /conf  ig/httpd/sites  . old  and  edit 
index. conf  changing  sites  to  sites. old  (cd 

/hsphere / local /conf ig/httpd/sites . old; perl  -pi  -e 
1 s/sites/sites .old/ ' index. conf) 

3 Copy  namevh . conf  to  namevh . old . conf 

4 Proceed  with  the  IP  migration. 

5 Add  the  following  lines  at  the  bottom  of  the 

/hsphere/local/config/httpd/httpd.conf  file: 

Include  /hsphere /local/ config/httpd/ sites. old/ [0-9] * . conf 
Include  /hsphere/local/ conf ig/httpd/namevh . old. conf 

On  the  DNS  servers: 

6 Add  your  old  DNS  IPs  to  the  /etc/named. conf  config  to  force  your  DNS 
servers  to  listen  to  the  old  IPs. 

Bind  your  old  IPs  to  the  NIC  on  your  servers. 
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Restarting  Services 


This  chapter  explains  how  to  start,  stop,  and  restart  daemon  services  on  Parallels  hl- 
Sphere  servers  under  Linux  and  FreeBSD. 

Important:  Do  not  stop  services  with  kill,  as  it  may  cause  information  loss!!! 

Note:  You  can  also  restart  services  from  the  Admin  CP  as  described  in  section  System 
Service  Management  of  Parallels  Pi-Sphere  Service  Administrator  Guide. 

Below  instructions  do  not  apply  to  restarting  DNS  server  (named)  for  Bind  8.x  (on  page 
57). 

> To  start  services,  run: 

Linux: 

# /etc/rc.d/init.d/<SERVICE>  start 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  start 

> To  stop  services,  run: 

Linux: 

# /etc/rc.d/init.d /<SERVICE>  stop 
FreeBSD: 

# /usr/local/etc/rc.d /<SERVICE>  stop 

> To  restart  services,  run: 

Linux: 

# /etc/rc.d/init.d /<SERVICE>  restart 
FreeBSD: 

# /usr/local/etc/rc.d /<SERViCE>  restart 

An  alternative  method  - and  often  more  appropriate  - is  to  stop  and  then  start  the 
service: 

Linux: 

# /etc/rc.d/init.d/<SERWCE>  stop 

# sleep  10 

# /etc/rc.d/init.d/<SERWCE>  start 


FreeBSD: 


Restarting  Services 


53 


# /usr/local/etc/rc.d /<SERVICE>  stop 

# sleep  10 

# /usr/local/etc/rc.d /<SERVICE>  start 

Note:  While  restarting  Parallels  H-Sphere  (on  page  54),  run  kiliaii  -9  java  after 
you  stop  and  before  you  start  CP. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss! 


Following  are  the  commands  to  put  in  place  of  <SERVICE>\ 


Service 

Linux 

FreeBSD 

Parallels  H-Sphere 
(tomcat) 

httpdcp 

apachecp . s 
h 

Parallels  H-Sphere 

Database 

(PostgreSQL) 

postgre 

sql 

010 .pgsql . 
sh 

Apache 

httpd 

apache . sh 

FTP 

prof tpd 

prof tpd . sh 

Qmail 

qmaild 

qmaild . sh 

SpamAssasin 

spamd 

spamd . sh 

ClamAV 

clamd 

clamd . sh 

PostgreSQL  (User  DB) 

postgre 

sql 

010 .pgsql . 
sh 

MySQL 

mysqld 

mysql- 
server . sh 

DNS  (Bind  9.3  and  up  (on 
page  198)) 

named 

named . sh 

1 map  Proxy 

imappro 

xy 

imapproxy . 
sh 
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Restarting  Parallels  H-Sphere  Control 
Panel 

> To  restart  Parallels  H-Sphere  Control  Panel: 

1 Log  into  the  CP  server  as  root. 

2 Run: 

Linux: 

/etc/rc.d/init.d/httpdcp  stop 
/etc/rc.d/init.d/httpdcp  start 

FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
/usr/local/etc/rc.d/apachecp. sh  start 


Restarting  Parallels  H-Sphere  Database 

Parallels  H-Sphere  database  is  used  to  store  system  data.  It  is  not  used  for  hosting. 
Usually,  it  is  located  on  the  same  server  as  the  control  panel  and  is  installed  and 
executed  under  user  pgsqi  (FreeBSD)  or  postgres  (Linux). 

> To  restart  the  database,  execute: 

Linux: 

# /etc/rc . d/init . d/postgresql  stop 

# sleep  1 

# /etc/rc . d/init . d/postgresql  start 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsqi . sh  stop 

# sleep  1 

# /usr/local/etc/rc . d/010 .pgsqi . sh  start 
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Restarting  Web  Server 

> To  restart  Web  server: 

1 Login  as  root. 

2 Execute  the  following  command: 

Linux: 

# /etc/rc . d/init . d/httpd  stop 

# sleep  10 

# /etc/rc . d/init . d/httpd  start 

FreeBSD: 

# /usr/local/etc/rc . d/apache . sh  restart 

> To  restart  FTP,  run: 

Linux: 

# /etc/rc . d/init . d/prof tpd  stop 

# sleep  1 

# /etc/rc . d/init . d/prof tpd  start 

FreeBSD: 

# /usr/local/etc/rc . d/prof tpd  restart 


Restarting  PostgreSQL  Server 

> To  start  PostgreSQL  server,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  start 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsql . sh  start 

> To  stop  PostgreSQL,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  stop 

FreeBSD: 

# /usr/local/etc/rc . d/010 .pgsql . sh  stop 

> To  restart  PostgreSQL,  run: 

Linux: 

# /etc/rc . d/init . d/postgresql  restart 

FreeBSD: 
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# /usr/local/etc/rc . d/010 .pgsql . sh  stop 

# sleep  10 

# /usr/local/etc/rc . d/010 .pgsql . sh  start 


Restarting  Mail  Server 

> To  restart  the  mail  server 

1 Login  as  root 

2 Execute  the  following  command: 

Linux: 

# /etc/rc.d/init.d/qmaild  stop 

# sleep  1 

# /etc/rc.d/init.d/qmaild  start 

FreeBSD: 

# /usr/local/etc/rc . d/qmaild. sh  stop 

# sleep  1 

# /usr/local/etc/rc . d/qmaild. sh  start 

> To  restart  the  auth  daemon  for  sqWebMail  under  Linux,  run: 

# /hsphere/local/sqwebmail/libexec/authlib/authdaemond  restart 


Restarting  MySQL  Server 

> To  start  MySQL  server,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  start 

FreeBSD: 

# /usr/local/etc/rc . d/mysql- server . sh  start 

> To  stop  MySQL,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  stop 

FreeBSD: 

# /usr/local/etc/rc . d/mysql -server . sh  start 

> To  restart  MySQL,  run: 

Linux: 

# /etc/rc . d/init . d/mysqld  restart 

FreeBSD: 
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# /usr/local/etc/rc . d/mysql- server . sh  start  stop 

# sleep  10 

# /usr/local/etc/rc . d/mysql -server . sh  start  start 


Restarting  Named 

> To  start,  stop,  or  restart  named  on  the  Parallels  H-Sphere  DNS  server: 

1 Log  in  as  root. 

2 Run  the  respective  command  below. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss!!! 

Linux: 

Starting:  / etc/ rc . d/ init . d/ named  start 
Stopping:  /etc/rc  . d/init . d/named  stop 
restarting:  /etc/rc.  d/init.  d/named  restart 

FreeBSD: 

For  Bind  9.3  and  up  (on  page  198): 

Starting:  /usr/local/etc/rc.  d/named,  sh  start 
Stopping:  /usr/local/etc/rc  . d/named,  sh  stop 
restarting:  /usr/local/etc/rc.  d/named.sh  restart 

For  Bind  8.x: 

Starting:  /usr/sbin/named  -u  named 
Stopping:  /usr/sbin/ndc  stop  -u  named 
restarting:  /usr/sbin/ndc  restart  -u  named 

Warning:  Without  "-u  named",  the  command  will  run  under  root. 

Usually,  a Parallels  H-Sphere  DNS  server  contains  a cron  DNS  check  which  starts 
every  1 or  2 minutes  and,  if  named  is  not  started,  starts  it.  Therefore,  do  not  feel 
alarmed  if  you  stop  named  and  see  that  it  keeps  working  for  another  several  minutes. 
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Control  Panel  Server 


Control  Panel  (CP)  is  the  Parallels  H-Sphere  logical  representation  for  managing 
servers  and  hosting  resources  via  the  web  interface.  It  is  implemented  as  a Java  servlet 
that  runs  on  its  own  Apache  server.  CP  is  a separate  logical  server  and  is  included  in 
every  Parallels  H-Sphere  configuration. 


In  this  chapter: 

Understanding  Control  Panel  Server  Configuration 59 

Logging  in  as  the  cpanel  User 65 
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Understanding  Control  Panel  Server 
Configuration 

This  section  provides  the  necessary  information  you  need  to  know  about  the 
configuration  of  Parallels  H-Sphere  control  panel  server. 

In  this  section: 

Installed  Software 59 

Interaction  Between  Servers 60 

Location  of  CP  Files  and  Directories 60 

The  Parallels  H-Sphere  Configuration  File 61 

Control  Panel  Apache  Server  Configuration 61 

Control  Panel  Back-End  Servlet  Engine 61 

Reseller  Configuration 61 

CP  SSL  Configuration 62 

CP  Apache  Log  Files 62 

CP  Traffic  Calculation 63 

The  Parallels  Fl-Sphere  System  Database 63 

CP  Mail  Queue 64 

Installed  Software 

On  control  panel  server  the  following  software  is  used: 

■ Apache  server  version  1 ,3.x  and  2.2.xSSL  support:  OpenSSL 

■ CP  back-end  servlet  engine:  Jakarta  Tomcat  (on  page  66) 

■ System  database:  PostgreSQL  7.4.x  and  up 

■ SiteStudio  - site  builder  optionally  installed  with  Fl-Sphere  on  the  CP  server. 
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Interaction  Between  Servers 

Servers  in  H-Sphere  clusters  communicate  only  through  the  Control  Panel.  There  is  no 
way  for  servers  like  web  and  DNS  exchange  commands  directly. 

To  communicate  with  Linux/Unix  servers,  CP  uses  Shell  or  Perl  scripts  via  SSH 
protocol  (port  22)  as  the  cpanei  user. 

Communication  between  the  CP  and  Windows  servers  is  performed  through  the  SOAP 
protocol,  http://www.w3.orq/TR/soap/,  (port  10125)  which  allows  for  cross-platform 
exchange  of  data  in  XML  documents  via  HTTP. 

Location  of  CP  Files  and  Directories 

By  default,  the  cpanei  user  home  directory  is  /hsphere/local/home/ cpanei. 

There  you  will  find  the  following  files  and  directories: 

■ apache  - CP  Apache  installation 

■ apache/etc  - CP  Apache  configuration 

■ apache/ etc/httpd.  conf  - CP  Apache  configuration  file 

■ shiva  - H-Sphere  related  binary  and  config  files 

■ shiva/psoft  config  - H-Sphere  config  files 

■ shiva/psoft  conf  ig/hsphere  . properties  - H-Sphere  COnfig  file 

■ shiva /psoft_config/HS_VERS ion  - file  that  contains  version  number  of  H- 
Sphere 

■ shiva/ shiva-tempiates  - H-Sphere  templates  location,  DocumentRoot  for 
Apache  server. 

■ shiva/shiva-tempiates/index . html  - Redirect  to  control  panel;  served 
when  the  http://cp.domain.com:8080/  CP  URL  is  accessed 

■ /hsphere/shared/SiteStudio/psof t conf ig/masonry . properties  - 

SiteStudio  config  file  (could  be  on  a different  server) 

IMPORTANT:  To  make  changes  in  these  files,  log  into  the  CP  server  as  the  cpanei 
user. 
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The  Parallels  H-Sphere  Configuration  File 

The  H-Sphere  configuration  file  should  be  located  at 

-'-cpanel/ shiva /pso ft  conf ig/hsphere  .properties 

1 CP  URL  configuration  - URL  by  which  H-Sphere  is  called: 

■ CP  HOST  = cp  . domain . com  — host  name 

■ CP_PORT  = 84  43  -port 

■ CP_PROTOCOL=https  : / / — protocol 

■ CP  URI  = /psof t/servlet/psof t . hsphere . CP 

Notes: 

■ This  is  not  the  only  place  where  those  settings  have  to  be  altered. 

■ URI  cannot  be  changed  here  at  the  moment. 

■ Make  sure  that  DNS  is  properly  configured  if  you  want  to  change  domain. 

■ Make  sure  to  alter  Apache  if  you  want  to  change  domain  and  port. 

2 Database  settings 

3 Log  file: 

log  4 j . appender . A1 . File=/var/ log /hsphere /hsphere  .log  - location  of 
the  log  file. 

Control  Panel  Apache  Server  Configuration 

CP  Apache  home  directory  is  /hsphere/local/home/ cpanel/apache. 

All  CP  Apache  server  configurations  are  placed  into  the  etc/ j serv  subdirectory  of  the 
Apache  home  directory:  /hsphere/local/home/ cpanel/ apache/etc/ j serv. 

This  directory  also  has  its  symlink: 

/hsphere/local/home/ cpanel/ apache/ conf. 

Control  Panel  Back-End  Servlet  Engine 

CP  server  uses  Jakarta  Tomcat  servlet  engine  and  is  automatically  installed  with 
Tomcat  (on  page  66)  embedded. 

Reseller  Configuration 

/hsphere/local/home/cpanel/apache/etc/sites/  contains  resellers’  SSL 
and  virtual  host  configuration. 

■ /hsphere/local/home/cpanel/apache/etc/ { reseller  main  account 
name } . conf  - reseller  Apache  virtual  host  configuration  file. 
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■ /hsphere/local/home/cpanel/apache/etc/ { reseller_main_account 
name } / - reseller  SSL  directory. 

Reseller  SSL  Configuration 

If  SSL  is  enabled  for  reseller,  the  following  files  are  placed  into  the  reseller  SSL 
directory: 

■ server . crt  - reseller  SSL  certificate 

■ server . key  - reseller  SSL  private  key 


CP  SSL  Configuration 

In  the  /hsphere/iocai/home/ cpanei/apache  CP  Apache  home  directory: 

■ etc/ ssi . crt/ server . crt  - file  with  server  SSL  certificates. 

■ etc/ssi . csr/server . csr  - file  with  SSL  signing  request. 

■ etc/ssl . key/server . key  - file  with  SSL/RSA  private  key. 


CP  Apache  Log  Files 

Log  files  are  located  in  the  /hsphere/ local /home/  cpanel/  apache /logs 

directory. 
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CP  Traffic  Calculation 

Traffic  generated  from  browsing  the  Control  Panel  is  not  included  in  the  summary 
traffic.  To  track  it,  Parallels  H-Sphere  owners  may  set  up  any  third-party  utilities. 

The  Parallels  H-Sphere  System  Database 

The  Parallels  H-Sphere  system  database  is  used  to  store  system  data.  In  normal 
Parallels  H-Sphere  configuration,  it  runs  on  PostgreSQL  server.  Usually,  the  system 
database  is  located  on  the  same  server  with  the  Control  Panel. 

The  system  database  is  not  for  user  hosting!  PostgreSQL  hosting  server  cannot  be 
installed  on  the  same  box  with  the  system  database! 


Note:  The  Parallels  H-Sphere  database  is  executed  under  the  pgsqi  or  postgres 
user. 


The  System  Database  Settings 

Database  settings  in  hsphere. properties  (this  should  be  enough  to  connect  to  db): 

DB  DRIVER  = org . postgresql . Driver 

DB_URL  = j dbc  : postgresql : //12  7 . 0 . 0 . 1/hsphere  - the  System  database 
name,  usually  hsphere 

db_user  = wwwuser  - the  system  db  user  name,  usually  wwwuser 

db_pas sword  = your_db_pas sword  - the  system  db  user  password 
DB_NEWID  = SELECT  nextval  ( ' ' { 0 } ' ' ) 

Logging  into  the  System  Database 

> To  log  into  the  system  database: 

1 Login  as  the  cpanel  user  (on  page  65)  to  the  server  where  the  system 
database  is  located  (usually,  CP  server). 

2 Enter  the  hsphere  database  (usually,  under  the  wwwuser  username): 
# psql  hsphere  [user_name] 


See  also  the  instructions  on: 

■ restarting  the  system  database  (on  page  54) 

■ backing  up  the  system  database  (on  page  432) 

■ upgrading  the  system  PostgreSQL  (on  page  92) 

■ the  system  database  optimization  (on  page  97) 

■ PostgreSQL  localization  (on  page  230)  (choosing  the  language  for 
PostgreSQL) 
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VACUUM  Utility 

The  Postgres  VACUUM  instruction  allows  cleaning  up  the  server  transactions.  Enter 
the  psql  server: 

# psql  hsphere  wwwuser 

and  type  in  the  password  set  in  hsphere  .properties. 

In  the  psql  command  line,  type  the  'vacuum  full'  command: 

vacuum  full; 

The  command  may  vary  in  different  versions  of  Postgres. 


Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete. 


CP  Mail  Queue 

The  mail  queue  file  is  assigned  to  store  unsent  CP  messages  (e.g.,  trouble  tickets, 
system  notifications,  mass  mail,  etc.)  when  CP  is  restarted  - formerly,  they  were  lost 
after  CP  restart.  Mail  queue  location  is  set  in  hsphere  .properties: 

MAIL_SWP=/hsphere/local/home/ cpanel/ shiva/mail . swp 
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Logging  in  as  the  cpanel  User 

Parallels  H-Sphere  control  panel  runs  under  the  cpanel  user  on  the  CP  server.  You 
need  to  log  in  as  cpanel  to  perform  many  administrative  tasks,  such  as  CP 
configuration,  customization,  access  the  system  databse,  running  console  Parallels  hl- 
Sphere  java  tools,  and  many  others. 

Under  cpanel,  Parallels  H-Sphere  control  panel  communicates  with  other  Parallels  Id- 
Sphere  boxes  via  SSH. 

> To  log  in  as  the  cpanel  user: 

1 Log  in  as  root  first: 

$ su  -l 

2 Log  in  as  the  cpanel  user: 

# su  -1  cpanel 


Logging  into  Parallels  H-Sphere  System 
Database 


To  run  SQL  queries  against  the  Parallels  H-Sphere  system  database,  you  need  to  be 
logged  into  Parallels  H-Sphere  system  database. 

> To  log  into  Parallels  H-Sphere  System  Database: 

1 Log  in  as  root  on  the  CP  server: 

$ su  - 

2 Log  in  as  the  cpanel  user: 

# su  -1  cpanel 

3 Connect  to  the  system  database: 

# psql  -d  hsphere  wwwuser 


Launching  Control  Panel  Cron  Jobs 

Along  with  the  cron  scripts  (on  page  33)  that  Parallels  H-Sphere  puts  into  its  physical 
servers'  crontabs,  there  are  several  background  jobs  that  are  executed  by  Parallels  H- 
Sphere  on  the  Control  Panel  server: 

■ Accounting  - does  recurrent  billing  for  end  users 

■ OverLimitCron  - checks  that  the  account  is  not  going  over  the  limit 

■ ResellerCron  - does  billing  for  resellers 

■ TrialCron  - suspends  expired  trial  accounts 

■ RevenueCron  - calculates  summary  billing  info 
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■ ContentMovingCron  - completes  the  process  of  moving  user  content 

■ FailedSignupsCron  - sends  emails  about  failed  signups  (every  5 minutes) 

■ TTAutocloseCron  - closes  trouble  tickets  answered  certain  time  ago 

■ VPSCron  - queries  the  status  of  creating  virtual  servers  (every  4 minutes) 

■ ecCron  - processes  the  externai  credits  table  and  adds  payments  performed 
within  an  external  payment  system  outside  Parallels  H-Sphere  to  this  table  as  the 
account  credits,  thus  integrating  external  payments  into  Parallels  H-Sphere.  Read 
more  about  external  credits  configuration  in  External  Credits  section  of  Parallels  hl- 
Sphere  Developer  Guide. 

These  cron  processes  use  the  iast_start  table  in  the  Parallels  H-Sphere 
database.  This  table  contains  the  following  fields: 

name  varchar(20)  NOT  NULL  PRIMARY  KEY, 
value  timestamp, 
last_user  int8 

When  Parallels  H-Sphere  is  restarted,  the  values  are  read  from  this  table  for  each  cron: 

■ name  - CP  cron  job  name  as  in  the  list  above  (corresponds  to  the  cron  tag's  name 
attribute  in  cron  XML  configuration  file) 

■ value  - last  time  that  cron  was  executed 

■ iast_user  - userjd  of  the  last  user  that  was  calculated  with  the  cron  (used  only 
for  accounting  and  overlimit). 

CP  Cron  XML  Configuration  Files 

CP  cron  settings  are  defined  and  customized  in  the  corresponding  XML  configuration 
file  described  in  CP  Cron  Configuration  section  of  Parallels  H-Sphere  Developer 
Guide.  You  can  add  new  custom  CP  crons  according  to  the  instructions  from  Adding 
Custom  CP  Cron  Jobs  of  Parallels  H-Sphere  Developer  Guide  and/or  change  cron  job 
settings  such  as  priority,  starting  time  and  period.  Such  customization  can  also  be  done 
by  means  of  Parallels  H-Sphere  packages  (see  Building  Packages  section  of  Parallels 
H-Sphere  Developer  Guide). 

Background  Job  Manager 

Background  Job  Manager  is  a utility  that  allows  you  to  enable,  start  and  disable 
selected  cron  jobs  from  the  CP  interface.  Cron  jobs  are  available  from  the  Admin 
control  panel,  the  Background  Job  System  section. 


Configuring  Tomcat 

Tomcat  installation  is  located  in  the  /hsphere/local/home/ cpanel/ j akarta 

directory. 
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Important:  The  core  Parallels  H-Sphere  directories  such  as  shiva,  shiva- 
tempiates,  psoft,  and  psoft-config  are  located  in  the 

/hsphere/ local /home/  cpanel /hsphere /WEB- INF/ classes/  directory  with 
Parallels  H-Sphere  classes  run  by  Tomcat.  Symlinks  to  these  new  locations  are  put  in 
place  of  the  old  directories  to  preserve  Parallels  H-Sphere  integrity  with  previous 
versions'  configuration. 


Tomcat  Configuration  Files 

Tomcat  configuration  files  are  located  in  the 

/hsphere/ local /home  / cpanel  / j akarta/ conf  directory: 

■ /hsphere /local /home/  cpanel/  j akarta/ conf/  server . xml  - XML  config 
file  for  Tomcat; 

■ /hsphere/local/home/cpanel/hsphere/WEB-INF/web . xml  - XML 

configuration  file  where  CP  servlet  configuration  is  set; 

■ /hsphere/local/home/cpanel/apache/etc/mod  j k . conf  - modjk 
configuration,  modjk  is  a Tomcat-Apache  plug-in  that  handles  the  communication 
between  Tomcat  and  Apache.  For  more  details,  see  Apache  documentation  on 
modjk  (http://iakarta.apache.org/tomcat/tomcat-3.3-doc/mod  ik-howto.html). 

Tomcat  Log  File 

Tomcat  log  file  is 

/hsphere /local /home/ cpanel/ j akarta/ logs/ catalina . out. 

Jakarta  connector  log  is 

/hsphere /local /home/ cpanel/ apache /logs /mod  j k . log. 

Restarting  Tomcat 

> To  stop  Tomcat: 

Run: 

/hsphere/local/home/cpanel/ jakarta/bin/catalina . sh  stop 

> To  start  Tomcat: 

Run: 

/hsphere/local/home/cpanel/ jakarta/bin/catalina . sh  start 

Tomcat  is  also  restarted  when  restarting  Parallels  H-Sphere  (Tomcat  is  restarted 
together  with  CP  Apache): 

/etc/init.d/httpdcp  restart 

Note:  Sometimes  you  might  need  to  restart  only  CP  Apache,  keeping  Tomcat  running. 
Then,  use  the  following  option: 

/etc/init . d/httpdcp  restartapache 
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Customizing  Tomcat  Environment  Variables 

The  file  -cpanei/setenv.  sh  is  designed  to  customize  Tomcat  environment 
variables. 

For  example,  to  allocate  Java  memory  in  the  range  between  64  MB  and  512  MB: 

1 Log  in  as  cpanei  user  (on  page  65)  . 

2 Stop  Tomcat  as  described  above. 

3 Open  ~ cpanei / setenv. sh: 

-bash-2 . 05b$  vi  ~cpanel / setenv . sh 

Set  the  following  line  in  the  file: 

export  CATALINA_OPTS="-Xms64M  -Xmx512M" 

4 Start  Tomcat.  You  will  see  something  like  this: 

Using  external  settings  -Xms64M  -Xmx512M 
+ java  version  1.4.x 

Using  CATALINA  BASE:  /hsphere/local /home/ cpanei / j akarta 
Using  CATALINA  HOME:  /hsphere/local /home/ cpanei / j akarta 
Using  CATALINA  TMPDIR:  /hsphere/local /home/ cpanei / j akarta/temp 
Using  JAVA  HOME:  /usr / j ava/ j dk 

5 Check  Java  to  make  sure  the  custom  settings  are  applied: 

-bash-2. 05b$  ps  auwx  | grep  java 

cpanei  3010  99.9  29.6  436776  27652  pts/0  S 05:54  0:09 
/usr/ j ava/ j dk/bin/ j ava  -Xms64M  -Xmx512M  - 
D j ava . awt . headless=true  - 

D j ava . endorsed. dirs=/hsphere/ local /home/ cpanei/ j akarta/ common/ 
endorsed  -classpath 

/usr/ j ava/ j dk/ lib /too Is . j ar : /hsphere/local /home/ cpanei/ j akarta 

/bin/bootstrap .jar: /hsphere/local /home/ cpanei/ j 

cpanei  3020  0.0  0.7  3680  664  pts/0  S 05:54  0:00  grep  java 
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Running  Java  Command  Line  Tools 

This  document  lists  java  command  line  tools  that  come  with  the  standard  Parallels  hl- 
Sphere  installation. 


IMPORTANT:  Before  running  a Java  tool,  make  sure  to  log  into  CP  server  as  the 
cpanel  user:  su  -1  cpanel 


In  this  section: 


DNSCreator 70 

IPMigratorFast 71 

PhysicalCreator 72 

PostApacheConfigs 73 

PostFTPConfigs 73 

ServerAliasesRenamer 74 

ChangeLServerld 75 

MIVAEmpresaFix 75 

KeyPairGenerator 76 

PGPEncrypter 76 

PGPMessageSigner 76 

PGPMessageVerify 77 

RepostResellerSSLConfigs 77 

ServiceZoneRenamer 78 

BillingEraser 78 

SetQuota 79 

UrchinReconfig 79 

OffLogs 80 

Reset  Balance 81 

RegeneratelpsFile 81 

LicenseExtractor 82 

VPSConvertor24_25 82 

MailRelayCorrector 83 
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DNSCreator 


NAME:  psof t . hsphere . tools . DNSCreator  - Parallels  H-Sphere  DNS  zones 
recreator. 


USAGE:  java  -Xms64M  -Xmx512M  psof t . hsphere . tools . DNSCreator  -m 
creation  method  [-dz]  -z  zonename 

OPTIONS: 

-m|  creation  method.  Possible  values:  db  or  rand: 

■ db  - pick  NS  servers  as  they  are  defined  in  the  Parallels  H-Sphere  database 

■ rand  - pick  NS  servers  randomly 

-dz  | — deiete_zones  - delete  zones  first.  Add  this  option  only  if  such  zones  already 
exist.  With  this  option,  DNS  creation  will  take  at  least  twice  more  time. 

-lids  | — logical-servers  - process  zones  which  are  on  the  logical  servers  with 
the  specified  IDs.  (This  option  makes  sense  if  you  have  more  than  four  logical  name 
servers  with  clearly  defined  Used  By  roles.) 

-pip  | — pServeriP  - specifies  a physical  server  by  its  primary  IP.  All  necessary 
logical  server  IDs  are  chosen  automatically.  Often  -pip  is  used  as  an  alternative  to  - 

lids. 


-z  | — zone  - recreate  only  one  specified  zone.  Without  this  option,  all  zones  will  be 
recreated. 


Note:  If  both  lids  and  -z  parameters  are  specified,  the  -z  parameter  will  be 
ignored. 


The  tool  also  accepts  zone  names  separated  by  line  breaks: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . DNSCreator  -m  creation  method 
[-dz]  < filename 

where  filename  is  the  name  of  the  file  which  contains  zone  names  separated  by  line 
breaks. 

DNS  Creator  is  used  in  Single  DNS  Configuration  (on  page  201),  Changing  IPs  on 
Systems  Using  NAT  (on  page  40),  Moving  DNS  (on  page  205)  and  in  Moving  Mail 
Accounts  (on  page  191). 
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IPMigratorFast 

NAME:  psoft.hsphere.tools. IPMigratorFast  - Parallels  Pi-Sphere  IP  migration  utility 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  [options] 
ipmigration . 

OPTIONS: 

— help  - shows  this  screen 

--ip-change  - Change  IP 

— repost-configs  - repost  IP  dependemd  resources 
— recreate-zone  - change  and  repost  DNS  records 
--service-zone  - change  service  zone  server  IP 
— custom-rec  - process  service  DNS  records 
— iServerids=, , . . . , - to  specify  logical  server  ids 
--repost-cp-ssl  - Repost  SSL  CP  VPIost  configs 
— clear-oid-ips  - remove  old  ips  from  database  and  servers 
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PhysicalCreator 

Physical  Creator  is  a java  class  that  generates  web  hosting  resources  and 
configurations  on  web,  win,  and  mail  servers  using  the  data  in  the  Parallels  H-Sphere 
system  database.  This  utility  is  used  to  recover  and  migrate  user  accounts.  It  is 
included  into  standard  Parallels  H-Sphere  installation. 

> To  run  Physical  Creator: 

1 Log  into  the  control  panel  server  as  cpanel  (on  page  65). 

2 Back  up  the  content  of  the  -cpanel/shiva/psof t/  directory. 

3 Run  Physical  Creator: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator 
OPTIONS 

where: 

■ xms64M  - recommended  minimum  memory  for  this  process 
xmx5i2M  - recommended  maximum  memory  for  this  process  OPTIONS: 

■ -h  | — help  - shows  the  list  of  available  options 

-rg  | — rgroup  - resource  group  to  perform  operations  with  The  following 
resource  groups  are  allowed: 

■ unixweb  - Unix  virtual  hosting  resources 

■ winweb  - Windows  virtual  hosting  resources 

■ mysql  - MySQL  resources 

■ mail  - Mail  resources 

■ -co  | — create-oniy  - performs  creation  resources  routines  only 

■ -do  | — delete-only  - performs  delete  resources  routines  only 

■ -rc  | — recreate  - performs  both  delete  and  creation  resources  routines 

■ -lid  | — lserverid  - process  accounts  on  logical  server  with  given  number 

■ -accs  | — accounts  - account  IDs  separated  by  comma,  e.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator 
-rg  winweb  -co  -lid  26  -accs  1725895  > creator.log  2>&1  & 

■ -st  | — start-from  - account  ID.  Process  will  start  from  this  account  ID.  E.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator 
-rg  winweb  -co  -lid  26  -st  1590055  > creator.log  2>&1  & 

Here  is  another  example  of  the  entire  command: 

bash-2 . 05a$  java  psoft . hsphere . tools . PhysicalCreator  -rg 
unixweb  -co  -lid  25 

This  command  will  create: 

■ empty  home  dirs 
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■ default  configuration  of  FTP  and  HTTP  virtual  hosts  on  unix  logical  server  with 
ID  25 

If  PhysicalCreator  hangs  on  one  of  the  accounts,  kill  it,  debug  the  issue,  and  then 
resume  the  process  starting  with  this  account,  e.g.: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  26  -st  1590055  > creator.log  2>&1  & 

4 Restore  the  backup  of  the  ~cpanel/shiva/psof t/  directory  to  the 
original  (recovery)  or  target  (move)  location. 

5 Restart  Parallels  H-Sphere  (on  page  54). 

PostApacheConfigs 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PostApacheConfigs  [-lid  n ] [ 

-ic  ] 

■ -lid  | — lserverid  n work  only  on  accounts  on  logical  server  with  passed 
number 

■ -ic  | --initcontent  initialize  content 

■ -h  | — help  print  this  message 


PostFTPConfigs 

NAME: 

psoft . hsphere . tools . PostFTPConfigs  - Parallels  H-Sphere  virtual  FTP  hosts 
generator  utility 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PostFTPConfigs  options 

OPTIONS: 

■ -h  | — help  - shows  this  screen 

■ -acc| — acountid  number  - process  only  account  with  given  number 

■ -lid  | — lserverid  - process  only  accounts  on  logical  server  with  given  number 

■ -all  | — all  - process  all  virtual  FTPs 


74 


Control  Panel  Server 


ServerAliasesRenamer 


NAME: 

psof t . h sphere .tools . ServerAliasesRenamer 

This  Parallels  H-Sphere  tool  recreates  server  aliases  for  resellers. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ServerAliasesRenamer 
[options] 

Usage: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ServerAliasesRenamer 

OPTIONS: 

■ — help  - shows  this  screen 

■ — xml  - run  the  tool  for  determined  xml  file 

■ — lserver  ...  - run  the  tool  for  determined  Logical  Server  IDs 
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ChangeLServerld 

NAME: 

psof t . hsphere . tools . ChangeLServerld  - changing  logical  server  id  in  Parallels 
H-Sphere  database 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ChangeLServerld 
[options] 

OPTIONS: 

■ — help  - shows  this  screen 

■ -a | — account  ACCOUNT_ID  -f| — from  L0GICAL_SERVER_ID_1  -t | — to 

LOGICALSERVERID2 

where 

■ account_id  - id  of  the  account  you  want  to  change; 

■ logi cal_server_i d_i  - id  of  the  logical  server  you  want  to  change  from; 

■ logi cal_server_i d_2  - id  of  the  logical  server  you  want  to  change  to; 

SAMPLE: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ChangeLServerld  -a  1000  -f  1 
-t  2 

This  tool  is  also  used  in  Moving  Mail  Accounts  (on  page  191). 


MIVAEmpresaFix 

"MIVAEmpresaFix"  utility. 

■ Adds  MivaEmpresa  resource  to  the  plans 

■ Adds  this  resource  to  users  which  already  have  MivaMerchant  in  use. 

■ Works  for  Unix  and  Windows  plans 

Usage: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools .MIVAEmpresaFix 
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KeyPairGenerator 

Parallels  H-Sphere  PGP  key  pair  generator. 

USAGE: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . KeyPairGenerator 

■ -i  | — identification  <youridentification  string> 

■ -s  | --subkeyidentif ication  <your  session  key  identification> 

■ -e  | — encryptphrase  <phrase  for  encryption/decryption  private  key> 

■ -prf  | — privatekeyf  ile  <file  where  private  key  will  be  saved> 

■ -pcf  | — pubiickeyf  ile  <file  where  public  key  will  be  saved> 

This  tool  is  used  in  PGP  Encryption  in  Trouble  Tickets  (on  page  111). 


PGPEncrypter 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPEncrypter 

■ -m  "This  is  a message  to  encrypt" 

■ -f  "This  is  a file  where  encrypted  phrase  will  be  saved" 

■ -k  "/path/to/PGP_Public_Key/file" 

This  tool  is  used  for  PGP  Encryption  in  Trouble  Tickets  (on  page  111). 


PGPMessageSigner 

Misconfiguration  Parallels  H-Sphere  PGP  message  signer. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPMessageSigner 

■ -m  | — message  <Message  to  sign>  or  -mf|--messagefile 
</path/to/file/with/message/to/sign> 

■ -f| — file  </path/to/file/for/signed/message> 

■ -k  | — key  </path/to/private/key/file> 

■ -p  | — codephrase  <private  code  phrase> 
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PGPMessageVerify 

Misconfiguration  Parallels  H-Sphere  PGP  message  verify. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PGPMessageVerify 

-f  | — messagef ile  </path/to/file/for/signed/message> 

-k  | — key  </path/to/public/key/file> 


RepostResellerSSLConfigs 

NAME: 

psoft. hsphere.tools. RepostResellerSSLConfigs  This  Parallels  H-Sphere  tool  recreates 
virtual  host  config  files  for  resellers. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . RepostResellerSSLConfigs 
[options] 

OPTIONS: 

— help  - shows  this  screen 
--process  - run  the  tool  for  all  config  files 

--reseller  <res  name  1>  <res  name  2>...<res  name  n>  - run  the  tool  for 
determined  reseller  user  names. 
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ServiceZoneRenamer 

Utility  for  changing  service  zone  name.  Changes  zone  name,  LServers  names,  rebuilds 
DNS. 

WARNING:  USE  ONLY  ON  EMPTY  INSTALLATION  OF  H-SPHERE. 

Usage: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . ServiceZoneRenamer  -oz 
zone_name  -nz 

zone_name 

■ -oz  | — oid_zone  Name  of  the  currently  present  service  zone 

■ -nz  | — new  zone  Name  which  should  be  set  to  service  zone 


BillingEraser 

Permanently  erases  billing  history  of  accounts.  Before  running  this  utility,  stop  Parallels 
H-Sphere  and  back  up  Parallels  H-Sphere  system  database. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . BillingEraser  --accounts 
list_of_account_ids  --resellers  list_of_reseller_ids 

NOTE: 

■ When  - -resellers  option  is  used,  the  utility  erases  billing  history  for  the  specified 
reseller  and  all  his  users. 

■ There  is  no  possibility  to  do  it  only  for  a reseller  account  (without  touching  users). 

■ Using  — accounts  and  — resellers  parameters  simultaneously  is  disabled. 

■ Specified  accounts  and  reseller  ids  are  delimited  with  commas. 


Control  Panel  Server 


79 


SetQuota 

NAME: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . SetQuota 

This  Parallels  H-Sphere  tool  resets  quota  on  a web  box  according  to  the  data  found  in 
Parallels  H-Sphere  DB  for  each  account  located  on  each  logical  server. 

SYNOPSIS: 

psoft . hsphere . tools . SetQuota  [options] 

OPTIONS: 

— help  - shows  help 

-lid  | — lserverid  - process  accounts  located  on  Logical  Server  with  specified  ID 
only 


UrchinReconfig 

NAME: 

psoft . hsphere . tools  .UrchinReconfig  - Regenerate  Urchin  config.  Used,  for 
example,  after  account  migration  to  restore  Urchin  settings  for  moved  domains. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . UrchinReconfig  [options] 

OPTIONS: 

— help  - shows  help 

-a  | — accounts  - list  of  account  IDs  delimited  with  or  'all'  for  all  accounts 
-s  | — servers  - list  of  logical  server  IDs  delimited  with  or  'all'  for  all  servers 

SAMPLE: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . UrchinReconfig  -a 
'1002,8383,1237'  -s  '12,35,37' 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . UrchinReconfig  -a  all  -s  all 
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OffLogs 

-bash-2. 05b$  java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  --help 

NAME: 

psoft . hsphere . tools . Of f Logs  - Regenerate  users'  logs  and  stats  config 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  [options] 

OPTIONS: 

■ — help  - shows  this  screen 

■ -a  | — accounts  list  of  account  IDs,  or  all  for  'all'  accounts, 

■ - delimiter  -s  | — servers  list  of  logical  server  IDs,  or  ’all'  for  all  servers, 

■ - delimiter  -e  | — erroriog  re-generate  errorlog  only 

■ -ag  | — agentiog  re-generate  agentlog  only 

■ _r  | — referreriog  re-generate  referrerlog  only 

■ -t  | — transf eriog  re-generate  transferlog  only 

■ -w  | — webalizer  re-generate  webalizer  only 

■ -m  | — modiogan  re-generate  modlogan  only 

■ -aw  | — awstats  re-generate  awstats  only 

SAMPLE: 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  -a  '1002,8383,1237'  - 
s '12,35,37' 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  -a  all  -s  all 
java  -Xms64M  -Xmx512M  psoft . hsphere . tools . Of f Logs  -s  24  -aw  -w 
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Reset  Balance 

NAME: 

psof t . hsphere .tools . ResetBalance 

This  Parallels  H-Sphere  tool  resets  billing  balance  using  different  criteria.  By  default, 
the  tool  runs  only  in  information  mode. To  fix  balances,  run  utility  with  — process 
option. 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . ResetBalance  options 

OPTIONS: 

-h  | — help  - shows  this  screen 

-acc  | — acountid  number  - process  only  accounts  with  given  number 
-ail  | — all  - process  all  accounts 

-b  | — balance  <id  baiance>  - process  accounts  with  balance  equal  to  cbalance 
for  process> 

-n  | — newbaiance  <new  baiance>  - set  balance  to  <balance  for  process> 

-d  | --description  - Ccredit  description>  - notes  which  will  be  added  to 
credit  operation 

--process  - to  force  process,  otherwise  only  affected  accounts  will  show 

RegeneratelpsFile 

NAME: 

psof t . hsphere .tools . RegeneratelpsFile 

This  Parallels  H-Sphere  tool  regenerates  file  /hsphere/iocai/network/ips  on 
Unix  physical  box 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . RegeneratelpsFile  options 

OPTIONS: 

■ — help  - shows  this  screen 

■ -all  - regenerate  on  all  physical  boxes 

■ -pid  - regenerate  on  physical  servers  with  specified  IDs 
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LicenseExtractor 

A tool  to  import  License  info  to  a file  or  print  it  to  console  screen. 

NAME: 

psof t . h sphere .too Is. LicenseExtractor 

Imports  License  info  to  a file  or  prints  it  to  console  screen. 

SYNOPSIS: 

java  psof t . hsphere . tools . LicenseExtractor  [options] 

OPTIONS: 

--help  - shows  this  screen 

--file  </path/to/f ile> 

</path/ to/f  iie>  - absolute  path  to  the  file  and  file  name  where  license  info  will  be 
imported; 

without  options  - shows  license  info  to  console  screen. 

VPSConvertor24_25 

A tool  to  convert  VPS  plans  and  accounts  during  the  update  from  Parallels  H-Sphere 
2.4.x  to  Parallels  H-Sphere  2.5  and  up. 

NAME: 

psof t . hsphere .tools . VPSConvertor2 4 25 

Converts  VPS  plans  and  accounts  during  the  update  from  Parallels  H-Sphere  2.4.x  to 
Parallels  H-Sphere  2.5  and  up 

SYNOPSIS: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . VPSConvertor24_25  [options] 

OPTIONS: 

— help  - show  this  help 

— all  - convert  all  VPS  plans  and  accounts  (recommended) 

EXAMPLE: 

su  -1  cpanel 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . VPSConvertor24_25  --all 
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Important:  VPS  converter  leaves  mail  quota  value  blank  in  converted  plans.  To  add 
DNS  zones  to  VPS  accounts  afterwards,  please  make  sure  you  set  mail  quota  value  in 
the  plan. 


MailRelayCorrector 

If  you've  updated  Parallels  H-Sphere  to  3.1  Beta  1 , run  this  tool  to  create  virtual  users 
for  every  mail  resource:  mailbox,  alias,  forward,  autoresponder,  mailing  list,  and  mail 
sms  if  mail  relay  is  enabled  for  mail  domain. 

NAME: 

psof t . h sphere .tools . MailRelayCorrector 

Processes  all  mail  resources  (mailbox,  forward,  alias,  autoresponder,  mailing  list,  sms) 
for  maildomains  with  enabled  mail  relays  and  creates  vitrtual  users  for  each  of  them. 

USAGE  EXAMPLES: 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . MailRelayCorrector  -a 
1233, 1254 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . MailRelayCorrector  -lid  7 
java  -Xms64M  -Xmx512M  psof t . hsphere . tools . MailRelayCorrector  -d 
my  maildomain.com 

java  -Xms64M  -Xmx512M  psof t . hsphere . tools . MailRelayCorrector  --all 

OPTIONS: 

■ -h  | — help  - shows  this  screen 

■ — all  or  without  any  parameter  - process  all  accounts 

■ -a  | — accounts  - process  accounts'  IDs  separated  by  comma 

■ -lid  | — lserverid  - process  accounts  on  logical  server  with  given  number 

■ -d  | — domains  - process  domains  separated  by  comma 
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Securing  Your  CP  Server  with  SSL 

This  document  gives  a step-by-step  instruction  on  how  to  secure  your  CP  apache 
server  with  a regular  SSL  certificate. 


Note:  You  can  secure  your  control  panel  with  a wildcard  certificate  if  you  install  it  on  the 
same  domain  name.  For  example,  if  your  cp  domain  name  is  cp . example . com,  you 
can  secure  it  by  installing  wildcard  certificate  to  example . com. 

We  recommend  that  you  configure  your  system  to  be  accessible  both  by  http  and  https, 
because  Parallels  SiteStudio  does  not  fully  support  https  protocol. 

> To  secure  your  CP  with  regular  SSL: 

1 Create  or  choose  a directory  to  store  SSL-related  files.  E.g.: 

#mkdir  cert 

Make  this  directory  available  only  for  root: 

#chmod  700  cert 
Go  to  this  directory: 

#cd  cert 

2 Generate  an  SSL  private  key  with  the  OpenSSL  utility: 

#openssl  genrsa  -des3  -out  server. key  1024 

When  prompted  for  a pern  phrase,  enter  any  combination  of  4 characters,  e.g. 

1 234.  A unique  private  key  will  be  generated  into  the  server . key  file. 

For  more,  read  modssl  documentation  (http://www.modssl.org/source/mod  ssl- 
2.8.1 6-1 .3-29.tar.qz). 

3 Copy  this  file  to  a secure  location.  You  will  need  it  later. 

4 Make  the  newly  generated  file  readable  only  by  root: 

#chmod  600  server. key 

5 To  view  the  content  of  the  private  key  file,  use  the  command: 

#openssl  rsa  -noout  -text  -in  server. key 

6 Remove  pass  phrase  from  the  private  key: 

#openssl  rsa  -in  server. key  -out  server . key . unsecure 

7 Now  you  don't  need  the  private  key  with  the  pass  phrase  any  more. 
Overwrite  it  with  the  private  key  without  the  pass  phrase: 

#cp  server . key . unsecure  server. key 

8 Generate  an  SSL  certificate  signing  request  based  on  the  private  key: 

#openssl  req  -new  -key  server. key  -out  server. csr 

You  will  have  to  answer  many  questions  related  to  your  company.  Your  answers  are 
required  to  be  included  in  the  certificate. 
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Note:  Common  name  is  the  URL  at  which  you  want  your  control  panel  to  be 
available,  e.g.  cp . yourdomain . com  (not  yourdomain  . com). 

9 Check  the  content  of  the  certificate  request  file: 

#openssl  req  -noout  -text  -in  server. csr 

If  you  find  a mistake  in  the  data  you  have  submitted,  you  can  re-generate  the 
request  anew. 

10  Make  sure  to  back  up  your  SSL  files: 

# mkdir  backup 

# chmod  700  backup 

# cp  ./*.*  backup/ 

11  Send  the  generated  CSR  file  to  a trusted  Certificate  Authority  for 
signing.  They  will  send  you  back  the  certificate.  Save  it  as  server. crt. 

12  To  view  the  content  of  the  certificate,  run: 

# openssl  x509  -noout  -text  -in  server. crt 

13  Save  the  private  key  and  the  certificate: 

# cp  -f  ./server. key 

/hsphere/ local/home/ cpanel/ apache/e tc/ssl . key/ 

# cp  -f  ./server. crt 

/hsphere/local/home/cpanel/apache/etc/ssl . crt/ 

14  Important:  Make  sure  to  back  up  the  ssl.key  and  ssl.crt  files  to  a safe 
location.  You  may  need  them  in  the  future. 

15  If  your  certificate  was  signed  by  a non-trusted  certificate  authority,  run 
the  following  command: 

# cp  -f  . /ca-bundle . crt 

/hsphere/local/home/cpanel/apache/etc/ssl . crt/ 

16  If  your  certificate  doesn't  require  chain  certificate,  skip  this  item. 
Otherwise,  do  the  following: 

a Store  chain  certificate  in  file: 

/hsphere /local /home/ cpanel/ apache /etc/ ssl . crt/ca . crt 

b Create  custom  CP  apache  config  template  if  you  do  not  have  any  (see 
Appendix  C of  Parallels  H-SPhere  Installation  Guide) 

c Add  line  (according  to  Step  2 "Edit  template"  in  the  above  mentioned 
document): 

SSLCertif icateChainFile 

/hsphere /local /home/ cpanel/ apache /etc/ ssl . crt/ca . crt 

to  file: 

/hsphere /local /home/ cpanel/ apache /etc/httpd . conf . tmpl . custom 

17  Open  the  file  hsphere  . properties: 

# vi 

/hsphere/ local/home/ cpanel/ shiva/ psof t_conf ig/hsphere . properti 
es 


and  change  lines: 
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CP_PORT  = 8080 
CP_PROTOCOL=http : / / 

to: 

CP_PORT  = 8443 
CP_PROTOCOL=https : // 

18  Restart  Parallels  H-Sphere  (on  page  54). 

19  Check  the  log  file: 

# vi  /hsphere/local/home/cpanel/apache/logs/ssl_engine_log 
Now  your  control  panel  must  be  available  at  both 

http : / / cp . yourdomain . com: 8080  and  https : / / cp . yourdomain , com: 8443 


In  this  section: 


Disabling  HTTP  Access 86 

Switching  Between  IP  and  Domain  Name 87 


Disabling  HTTP  Access 

We  don't  recommend  disabling  HTTP  access,  because  it  is  required  by  Parallels 
SiteStudio.  Still,  if  you  have  chosen  to  disable  http,  do  the  following: 

1 Open  the  file  ~cpanel/apache/etc/httpd.  conf 

2 If  you  would  like  to  exclude  http  access  and  use  only  secure 
connections,  comment  out  the  line  "Listen  8080"  in  the  block 

IfDefine  SSL. 

3 Restart  Parallels  H-Sphere  (on  page  54). 
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Switching  Between  IP  and  Domain  Name 

You  cannot  have  your  control  panel  available  both  by  domain  name  and  IP  address. 
You  can  have  only  one. 

> To  switch  between  IP  and  domain  name  control  panel  access: 

1 Open  the 

/hsphere / local /home/ cpanel / shiva /psof t_conf ig/hsphe re 
. properties  file. 

2 Set  the  value  of  cp_host  to  your  new  cp  url/ip.  Make  sure  not  to 
change  the  value  of  the  path_site_studio  property. 

3 Save  and  exit  the  file. 

4 Restart  Parallels  H-Sphere  (on  page  54). 

Check  for  feedback  from  Parallels  H-Sphere  owners  on  how  to  use  Parallels  H-Sphere 
with  POP3  SSL,  IMAP  SSL,  SMTP  SSL  and  SFTP: 
http://forum.psoft.net/showthread.php?threadid=3187. 


Upgrading  Java 

This  section  explains  how  to  upgrade  Java  SDK  on  the  Parallels  H-Sphere  control 
panel  server. 

In  this  section: 


Supported  Versions 87 

Upgrade  Procedure 88 


Supported  Versions 

Linux 

It  is  recommended  that  Linux  owners  use  the  Java  SDK  1 .4.2  by  Sun  Microsystems 
(http://iava.sun.eom/i2se/1 .4.2/).  This  applies  to  all  products  in  the  RedHat  Linux 
product  line. 

FreeBSD 


Java  1 .4.2  is  implemented  on  CP  server  under  FreeBSD  4.x.  Please  update  your 
Parallels  H-Sphere  to  the  latest  version  where  you  can  update  Java  to  1 .4.2. 
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Upgrade  Procedure 

You  have  two  alternative  ways  to  upgrade  Java.  Choose  one  of  the  alternatives  below. 

In  this  section: 


Automatically  By  Means  of  Parallels  H-Sphere  Update  Script 88 

Manually  from  Java  1 .4.2  SDK  by  Sun  Microsystems  (Linux  Only) 88 


Automatically  By  Means  of  Parallels  H-Sphere  Update  Script 

> To  upgrade  Java  automatically: 

1 Log  into  the  CP  server  as  root: 

# su  - 

2 Download  the  upgrade  package  for  your  Parallels  H-Sphere  version 
from  http://download.hsphere.parallels.com.  untar  it  and  execute. 

3 In  the  upgrade  script  interface,  type  the  following  option  to  update 
Java  to  1 .4.2: 

javaupdate 

This  will  update  your  Java  to  1 .4.2  and  will  also  update  your  Parallels  H-Sphere  Java 
classes. 

Manually  from  Java  1.4.2  SDK  by  Sun  Microsystems  (Linux 
Only) 

> To  upgrade  Java  manually: 

1 Log  into  the  CP  server  as  root: 

2 

3 

4 Set  up  Java  JDK  1 .4.2  following  the  instructions  by  Sun  Microsystems 
(http://iava.sun.eom/j2se/1 . 4. 2/install-li  nux.html). 

5 Update  symlink  /usr/ j ava/ j dk/  to  point  to  your  installation,  for 
example  to  /usr/ j ava/ jdkl  . 4 . 2_06. 

If  you  don't  have  the  /usr/java/jdk/  symlink: 

1 . Create  it  to  point  to  your  installation. 


# su  - 

Stop  Parallels  H-Sphere: 

# /etc/rc.d/init.d/httpdcp  stop 
Stop  all  java  processes  on  your  system: 

# killall  java 
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2.  In  the  file 

/hsphe re /local /home/ cpanel /apache/ etc/ j serv/ j serv . propertie 

s,  set  the  following: 

wrapper . bin=/ usr/ j ava/ j dk/bin/ j ava 

wrapper . classpath=/usr/ j ava/ j dk/ j re/lib/rt . j ar 

6 Skip  this  step  if  you  don't  run  Parallels  SiteStudio. 

Open  the  file  /hsphere/ shared/ SiteStudio/ imaker . sh  and  check  if  it  has 
the  line: 

JAVA_HOME= ' su  -1  cpanel  -c  'echo  $ JAVA_HOME ' 

If  it  doesn't,  update  the  JAVA_HOME  parameter  in  this  file,  e.g.: 

JAVA  HOME=/usr/ java/ jdkl . 4 . 2 

7 To  ensure  correct  work  with  OpenSRS,  download  the  "Unlimited 
Strength"  Jurisdiction  Policy  Files  from 

http://iava.sun.eom/products/ice/index-14.html#UnlimitedDownload. 

The  files  for  version  1 .4.2  can  be  downloaded  from  page 
http://iava.sun.eom/j2se/1 . 4. 2/down  load.  html#docs,  section  "Other 
Downloads".  Put  the  files  in  the  directory 

java_home/ j re/lib/ security  where  java_home  is  the  Java 
SDK  home  directory. 

8 Upgrade  to  one  of  the  latest  versions  of  Parallels  H-Sphere. 

9 Start  Parallels  H-Sphere: 

# /etc/rc.d/init.d/httpdcp  start 


Converting  Parallels  H-Sphere  System 
Database  from  MS  SQL  to  PgSQL 

PgSQL  is  the  only  supported  format  for  the  Parallels  H-Sphere  system  database.  The 
conversion  procedure  suggested  in  this  section  takes  two  steps  listed  below. 


In  this  section: 


Step  1 . Convert  Database  from  MSSQL  Server  to  MySQL 90 

Step  2.  Convert  Database  from  MySQL  Server  to  PgSQL 91 
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Step  1 . Convert  Database  from  MSSQL  Server  to 
MySQL 

> To  Convert  database  from  MSSQL  to  MySQL: 

1 Rename  the  following  fields: 

■ table  esc_  rules:  rename  interval  to  interval2 

■ table  revenue:  rename  usage  to  usage2 

This  must  be  done  to  avoid  conflicts  in  MySQL,  and  must  be  changed  back  in  the 
MySQL  dump. 

2 Download  the  mssql2mysql . exe  convertor  from 
http://download.hsphere.parallels.com/shiv/db  convert/mssql2mysql.e 

xe 

3 Start  mssql2mysql . exe  and  configure  setting  for  MSSQL/MySQL 
servers  (hosts,  usernames,  passwords,  new  database  name  for  mysqi) 
and  save  settings. 

If  you  get  warnings  about  missing  componenets,  download  and  run  the 
MtaEdt22.exe  utility  from 

http://download.hsphere.parallels.com/shiv/db  convert/MtaEdt22.exe.  It  will 

download  and  set  up  all  missing  components. 

4 Click  Connect  to  connect  to  mssql  database  and  select  the  database 
to  convert. 

5 Select  all  necessary  tables  or  press  Select  ah  to  select  all  tables 

6 Click  start  to  start  database  conversion 

7 To  see  the  database  after  the  conversion: 

mysqi  hsphere  mysqi  (for  example) 
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Step  2.  Convert  Database  from  MySQL  Server  to  PgSQL 

Execute  all  suggested  queries  in  one  transaction.  Replace  PG_HOST_NAME  with  the 
name  of  the  host  where  PgSQL  server  is  running,  like  example . com. 

1 Download  the  mysql/pgsql  dump  convertor  archive  from 
http://download.hsphere.parallels.com/shiv/db  convert/my2pq.tqz  and 

unpack  it: 

tar  zxvf  my2pg . tgz 

2 Dump  tables  and  data  from  mysql: 

mysqldump . exe  hsphere_mysql  > hsphere_dump 

3 As  the  result,  you  will  get  a MySQL  dump  with  table  structure  and 
data  (hsphere_dump) 

4 In  MySQL  dump,  rename  the  following  fields: 

■ table  esc_  rules:  rename  interval2  to  interval 

■ table  revenue:  rename  usage2  to  usage 

5 Convert  mysql  dump  to  pgsql  dump: 

my2pg.pl  hsphere_dump  > hsphere_pgsql 

As  the  result,  you  will  get  a converted  dump  (hsphere_pgsql) 

6 Replace  timestamp  to  timestamp  with  time  zone. 

7 If  the  database  already  exists,  delete  it: 

dropdb  -h  PG_HOST_NAME  -U  wwwuser  hsphere^pgsql 

8 Create  a new  (empty)  database: 

createdb  -h  P G_HO S T_NAME  -U  wwwuser  hspherejpgsql 

9 Restore  the  database  from  dump  (tables  and  data): 

psql  -h  P G_HO S T_NAME  -d  hspherejogsql  -U  wwwuser  -f 
hspherejpgsql  > migrate_errors 

-d  - database  name 
-f  - file  with  dump 

As  a result,  you  will  see  convertion  results  in  the  migrate_errors  file. 

10  Connect  to  the  database  and  check  all  tables  and  data: 

psql  -h  P G_HO S T_NAME  -d  hsphere_pgsql  -U  wwwuser 

11  For  each  record  of  the  sequences  table,  run  the  following  two 
commands  against  the  Postgres  DB: 

CREATE  SEQUENCE  "<seq_name>"  start  <id>; 

SELECT  nextval  ( ' <seq_name> ' ) ; 

For  example,  for  the  record  newid  ->  27  64  88,  execute  the  following  SQL 
statements: 

CREATE  SEQUENCE  "newid"  start  276488; 

SELECT  nextval  ('newid'); 
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Upgrading  System  Postgres 

This  document  expalins  how  to  update  your  system  and  user  PostgreSQL  from  version 
7.3.x  to  version  7.4.7  which  is  faster,  uses  server  memory  more  effectively,  and 
includes  security  fixes. 


Important:  If  your  PosgtreSQL  version  is  lower  than  7.3,  please  upgrade  it  to  v.  7.3 
first. 

> To  check  your  PostgreSQL  version: 

1 Log  into  your  control  panel  server  as  root: 

su  - 

2 Execute: 

psql  — version 
This  update  includes  the  following: 

■ PostgreSQL  Security  Release  for  7.4.7,  http://www.postqresal.org/about/news.281 

■ Postgres  server  and  client  software  updates,  including: 

■ perl  client  library  on  all  boxes  (install  if  missing) 

■ server  software  with  data  conversion  to  the  current  version  format 

■ FreeBSD  eliminated  PL/PgSQL  parser  vulnerability  to  buffer  overflows 
(http://www.freebsd.org/ports/portaudit/6b4b0b3f-81 27-1 1 d9-a9e7- 

0001 020eed82.html). 

Make  sure  that  your  system  satisfies  the  following  requirements: 

■ Current  PostgreSQL  updated  to  version  7.3. 

■ hsphere  database  converted  to  UNICODE  (on  page  94). 

IMPORTANT:  You  are  highly  recommended  to  backup  your  databases  into  a directory 
other  than  Postgres  home  directory  so  you  do  not  lose  data  if  anything  goes  wrong. 

> To  upgrade  system  Postgres: 

1 Log  into  your  control  panel  server  as  root: 

su  - 

2 Download  the  PostgreSQL  7.4.7  upgrade  script  from  the  downloads 
site: 

For  Linux: 

wget  http : //download. hsphere . parallels . com/ shiv/HS/u-pgsgl- 

7.4.7. tar . gz 

For  FreeBSD: 

fetch  http : //download . hsphere .parallels . com/ shiv/HS/u-pgsgl- 

7.4.7. tar . gz 
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3 Unpack  the  archive: 

tar  - zxf  u-pgsql- 7 .4.7. tar . gz 

4 Enter  the  unpacked  directory: 

cd  u-pgsql- 7 . 4 . 7 

5 To  upgrade  all  PostgreSQL  servers,  run  the  update,  sh  script: 
sh  update . sh 

To  run  the  script  and  view  the  messages  that  appeared  during  installation,  run  the 
following  command: 

sh  update . sh  | tee  update . log 

It  will  copy  the  messages  to  the  log  file. 

Note:  If  the  script  runs  into  an  error  on  a user  database  server,  you  are  notified  of  it,  the 
script  skips  the  box  and  turns  to  the  next  one.  When  you  are  through  with  the  update, 
see  recover-howto-eng.txt  file  to  lean  how  to  recover  the  box  that  hasn't  got 
updated.  When  you  fix  the  error,  you'll  need  to  update  this  box  manually. 
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Converting  Parallels  H-Sphere  Database 
To  UNICODE 


The  system  database  must  be  in  UNICODE  (UTF-8). 

> To  convert  your  database  to  Unicode: 

1 Stop  the  control  panel 

Log  in  as  root  and  stop  the  control  panel: 

For  Linux: 

/etc/rc.d/init.d/httpdcp  stop 
killall  -9  java 

For  FreeBSD: 

/usr/local/etc/rc.d/apachecp. sh  stop 
killall  -9  java 

2 Find  out  your  current  database  encoding 
Type: 

su  -1  cpanel  -c  'psql  hsphere ' 
hsphere#  \encoding 

If  the  encoding  is  UNICODE  (UTP-8),  you  have  found  what  you  need.  If  not,  the 
next  step  is  to  dump  Parallels  H-Sphere  system  database. 

3 Dump  Parallels  H-Sphere  system  database 

1 . Create  and  enter  backup  directory: 

mkdir  pg_backup 
cd  pg_backup 

2.  Get  the  password  for  wwwuser.  You’ll  need  it  to  query  the  database: 

cat  ~cpanel/shiva/psoft_config/hsphere. properties  | grep  PASS 

3.  Dump  Parallels  H-Sphere  system  database. 

Export  schema: 

pg  dump  -u  -s  -f  schema. db  hsphere 

chmod  600  schema. db 

cp  -p  schema. db  schema  backup. db 

Export  data: 

pg  dump  -u  -a  -f  data . db  hsphere 

chmod  600  data.db 

cp  -p  data.db  data_backup . db 

Notes: 

1 . If  your  system  database  is  large,  the  dump  can  take  several  hours  to 
complete.  You  can  speed  it  up  by  setting 

f sync=of f 
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in  postgresqi . conf . When  you  are  done,  unset  this  option  back  for  safety 
reasons. 

2.  The  dump  file  is  created  with  644  permissions  by  default;  you  need  to  set 
more  secure  600  permissions  to  prevent  the  data  from  being  read  by  other 
users. 

4.  For  additional  security,  you  may  disallow  access  to  the  backup  directory  for  all 
other  users: 

chmod  700 

4 Convert  the  dump  to  UNICODE. 

Convert  the  dump  into  Unicode  with  the  iconv  utility. 

Linux: 

iconv  --from-cod e=<REGIONAL_ENCODING>  --to-code=UTF-8  -o 
utf_data.db  data.db 
mv  utf  data.db  data.db 

FreeBSD: 

iconv  -f  <REGIONAL_ENCODING>  -t  UTF-8  data.db  > utf  data.db 
mv  utf  data.db  data.db 

If  your  dump  file  exceeds  2GB: 

1 . Split  it  into  smaller  files,  1GB  each: 
split  -b  1024m  data.db  data  db 

2.  Run  iconvf  or  for  each  of  these  files  to  convert  them  to  UNICODE: 

iconv  --f rom-code=</?EG/OW4L_EWCOD/WG>--to-code=UTF-8  -o 
utf_data_db . aa  data_db.aa 

iconv  — from-code=<REGIONAL_ENCODING> — to-code=UTF-8  -o 
utf_data_db . ab  data_db.ab 

3.  Join  them  back  into  data.db: 

cat  utf  data  db.aa  utf  data  db.ab  utf  data  db.ac  ...  > data.db 


Flere,  <REGIONAL_ENCODING>  is  the  source  encoding.  For  example,  for  native  US 
English  encoding: 

Linux: 

iconv  --f rom-code=ISO-8859-l  --to-code=UTF-8  -o  utf  data.db 
data . db 

FreeBSD: 

iconv  -f  ISO-8859-1  -t  UTF-8  data.db  > utf  data.db 

The  resulting  data . db  file  will  contain  the  data  converted  to  Unicode. 

For  better  security,  run  the  following  command: 
chmod  600  data.db 

5 Save  the  postgres  directory  in  a backup  location. 

1 . Stop  the  database: 
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For  Linux: 

/etc/rc.d/init.d/postgresql  stop 
For  FreeBSD: 

/usr/local/etc/ rc . d/010 .pgsql . sh  stop 

2.  Save  the  postgres  directory: 

For  Linux: 

cp  -pR  ~postgres/data  . / 

For  FreeBSD: 

cp  -pR  ~pgsql/data  . / 

3.  Start  the  database: 

For  Linux: 

/ etc/ rc . d/ init . d/postgresql  start 
For  FreeBSD: 

/usr/local/etc/ rc . d/010 .pgsql . sh  start 

6 Recreate  Parallels  H-Sphere  database. 

1 . Delete  old  Parallels  Fl-Sphere  database: 

# su  -1  cpanel 
$ dropdb  hsphere 

2.  Create  database: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 

3.  Create  Parallels  Fl-Sphere  DB  schema: 

psql  -q  -U  wwwuser  -f  schema. db  hsphere 

4.  Import  Parallels  Fl-Sphere  system  data: 

psql  -q  -U  wwwuser  -f  data.db  hsphere 

Note:  If  you  face  problems  with  importing  data,  please  see  the  Troubleshooting 
(on  page  97)  section  in  CP  Acceleration  guide. 

5.  If  you  added 

f sync=of f 

to  postgresql.conf,  don't  forget  to  delete  it. 

6.  Start  the  Control  Panel  (on  page  54). 
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Accelerating  Control  Panel 

When  your  Control  Panel  is  slow  or  you  have  high  CPU/memory  load,  you  can  do  a few 
steps  to  accelerate  its  performance. 


In  this  section: 


Parallels  H-Sphere  Java-related  Issues 97 

Optimizing  Parallels  H-Sphere  System  Database 99 

Troubleshooting 104 


Parallels  H-Sphere  Java-related  Issues 

1.  Tomcat  Optimization 

Customize  Tomcat  environment  variables  (on  page  66). 

2.  NFU  Cache  Optimization 

NFU  cache  parameters  have  to  be  set  depending  on  your  server  memory  size  and  the 
number  of  accounts  and  domains  in  your  system.  If  a lot  of  new  accounts/domains  are 
added  to  Parallels  H-Sphere,  we  recommend  to  reconfigure  NFU  cache. 

> To  reconfigure  NFU  cache: 

1 Stop  the  Control  Panel. 

2 Set  NFU  parameters  in  hsphere  . properties. 

Check  hsphere . log  for  NFU  messages: 

grep  NFU  /var/log/hsphere/hsphere . log 

You  would  receive  the  lines  like  these: 

2003-02-26  08:08:29,190  [Thread-11]  DEBUG  psoft . hsphere . CP  - 
Resource  NFU  cache : initial  size:5000  size:142  max  size:5000 
rate : 0 . 0 

2003-02-26  08:08:29,190  [Thread-11]  DEBUG  psoft . hsphere . CP  - 
Resourceld  NFU  cache : initial  size:25000  size:161  max 
size:25000  rate:0.87 

2003-02-26  08:08:29,190  [Thread-11]  DEBUG  psoft . hsphere . CP  - 
SharedObject  NFU  cache : initial  size:5000  size:0  max  size:5000 
rate : 0 . 0 
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Here,  you  should  pay  attention  to  the  "size"  and  "rate"  parameters.  If  the  "initial  size" 
is  close  to  the  "max  size"  and  rate  is  lower  than  0.75,  it  is  appropriate  to  increase 
the  size  of  NFU  cache.  For  this,  you  need  to  insert  two  parameters  to 
hsphere. properties: 


NFU_CACHE_MULTIPLIER  = 5 
NFU_CACHE_MULTIPLIER_MAX  = 10 

In  this  example,  cache  size  would  increase  five  times,  and  if  necessary  (e.g.,  for 
accounting)  it  could  be  increased  ten  times. 

3 Start  the  Control  Panel. 
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Optimizing  Parallels  H-Sphere  System  Database 

To  optimize  the  system  database,  perform  operations  listed  in  this  section. 

In  this  section: 


Converting  Bigint  to  Int4 99 

Updating  Moddb 100 

Performing  VACUUM 101 

Optimizing  Postgres 102 

Upgrading  Postgres  to  the  Latest  Version 104 


Converting  Bigint  to  Int4 

Skip  this  procedure  if  you  have  have  already  performed  it. 

Postgres  migration  from  int8  to  int4  is  very  effective  if  you  host  more  than  500 
accounts.  (By  default,  Postgres  can't  index  fields  of  the  int8  type.) 

You  need  to  perform  it  once  at  any  time. 

For  this  procedure,  find  the  partition  with  sufficient  amount  of  free  space. 

1 Stop  the  Control  Panel  (check  hsphere . log  that  no  crons  are 
running) 

2 Export  schema: 

pg  dump  -u  -s  -f  db  old.db  hsphere 
chmod  600  db  old.db 
cp  db  old.db  db . db 

Note:  dump  file  is  created  with  644  permissions  by  default;  you  need  to  set  more 
secure  600  permissions  to  prevent  the  data  from  being  read  by  other  users. 

3 Convert  int8  to  int4: 

vi  db . db 

In  vi  editor,  change  every  instance  of  bigint  and  int8  to  int4  by  typing  the  following 
commands: 

%s /bigint /int 4 /g 
%s/int8/int4/g 

4 Then,  still  editing  db . db  in  vi,  change  type  back  to  int8  for  the 
ip_num  column  in  the  l_server_ips  table  and  its  index. 

a find  the  ip_num  definition  in  the  create  table  "i_server_ips"  ( ... 

) ; command: 

ip_num  int4  NOT  NULL 

- and  change  int4  to  int8; 
b find  the  index  creation  command: 
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CREATE  INDEX  "1  server  ips  numkey"  on  "1  server  ips"  using 
btree  ( "ip  num"  "int4  ops"  ) ; 

- and  change  int4_ops  to  int8_ops. 

5  Export  Data: 

pg  dump  -u  -a  -f  data . db  hsphere 
chmod  600  data.db 


Note:  dump  file  is  created  with  the  644  permissions  by  default;  you  need  to  set 
more  secure  600  permissions  to  prevent  the  data  from  being  read  by  other  users. 

6 Recreate  DB: 

dropdb  -U  wwwuser  hsphere 
createdb  -U  wwwuser  hsphere 

7 Create  Schema: 

psql  -q  -U  wwwuser  -f  db.db  hsphere 

8 Import  Data: 

psql  -q  -U  wwwuser  -f  data.db  hsphere 

9 Start  the  Control  Panel. 

Updating  Moddb 


Note:  Prior  to  running  moddb,  update  your  Parallels  H-Sphere  to  the  latest  version. 


Moddb  is  one  of  the  scripts  included  in  the  Parallels  H-Sphere  update.  However,  it  is 
not  automatically  performed  during  the  Parallels  H-Sphere  installation.  You  should 
launch  it  manually  and  only  once.  To  do  this: 

1 Stop  the  Control  Panel. 

2 Make  moddb: 

1 . Download  the  Parallels  H-Sphere  update  (to  the  installed  version) 

2.  Run  the  update  script.  For  example,  for  the  Parallels  H-Sphere  2.3.2  Patch  5 
update  script: 

#sh  ./U23.2P5 

3.  Choose  the  moddb  option. 

This  option  will  back  up  old  Parallels  H-Sphere  database  and  modify  Parallels  H- 
Sphere  DB  scheme  (increase  some  fields  length,  e.g:  email,  notes, 
suspend/resume  reason  etc.). 

Note:  You  may  be  prompted  for  your  Parallels  H-Sphere  DB  password  under 
Postgres  versions  starting  from  7.2.x.  Enter  the  password  to  complete  the 
procedure. 

3 Start  the  Control  Panel. 
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Performing  VACUUM 

VACUUM  should  be  performed  regularly  (e.g.,  once  a week).  You  may  put  the 
corresponding  script  into  cron. 

Mind,  however,  that  this  procedure  requires  a lot  of  system  resources  and  creates  a 
high  server  load. 

We  recommend  you  to  back  up  the  database  before  performing  vacuumdb.  Be  careful: 
if  the  server  gets  down  during  this  process,  some  data  may  be  lost! 

To  backup  your  system  database,  run  the  hs_bck  script: 

/hsphere/ shared/ scripts/cron/hs_bck , 

or 

cd  /hsphere/shared/backup 
. /hs_bck  hs_bck . cfg 

Do  the  following  procedure  to  apply  VACUUM  to  your  system: 

1 Log  into  the  server  as  root: 

su  - postgres 
for  FreeBSD: 
su  - pgsql 

2 Connect  to  the  database: 

psql  -U  wwwuser  -d  hsphere 

3 Do  vacuum: 

hsphere$  vacuum  full; 
or 

vacuum  analyze; 
or 

vacuum; 

depending  on  the  PostgreSQL  server  version 

Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete! 
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Optimizing  Postgres 

You  can  enhance  CP  productivity  by  optimizing  some  Postgres  parameters  in  the 
postgresqi . conf  file.  Default  values  of  these  parameters  are  intended  for  less 
powerful  workstations,  and  therefore  these  values  should  be  significantly  increased  for 
better  performance  on  servers  with  multiple  CPUs,  large  RAM,  and  with  large  and 
intensively  used  databases. 

Consider  reconfiguration  of  the  following  parameters  (please  refer  to  PostgreSQL 
documentation,  http://www.postqresql.orq/docs/7.4/interactive/runtime-confiq.html,  for 
details): 

■ shared_buf  f ers  - size  of  shared  buffers  for  the  use  of  Postgres  server 
processes.  It  is  measured  in  disk  pages,  which  are  normally  8kB.  Default  value  is 
64,  i.e.,  512  kB  RAM.  We  recommend  increasing  this  parameter: 

■ for  middle-size  database  and  256-512  MB  available  RAM:  to  16-32  MB  (2048- 
4096) 

■ for  large  database  and  1 -4  GB  available  RAM:  to  64-256  MB  (81 92-32768) 

■ sort_mem  - size  of  RAM  allocated  for  sorting  query  results.  Measure  unit  is  IkB. 
Default  value  is  1024.  We  recommend  setting  this  parameter  to  2-4%  of  available 
RAM. 

■ wai_buf  fers  - size  of  the  transaction  log  buffer.  Measure  unit  is  8kB.  Default 
value  is  8.  It  can  be  increased  to  256-512  for  better  processing  of  complex 
transactions. 

■ max_connections  - the  maximum  number  of  connections  to  a database  at  a time. 
Default  value  is  32.  We  recommend  increasing  it  to  at  least  64. 

■ checkpoint_segments  - maximum  distance  between  automatic  WAL  (Write- 
Ahead  Log)  checkpoints.  Measured  in  log  file  segments  (each  segment  is  normally 
16  megabytes).  Default  value  is  3.  We  recommend  increasing  this  parameter  if  data 
is  being  actively  accessed  and  modified. 

■ checkpoint_timeout  - maximum  time  for  transaction,  in  seconds.  Default  value 
is  3000.  We  recommend  increasing  this  parameter  at  least  10  times. 

■ ef  f ective_cache_size  - sets  the  optimizer's  assumption  about  the  effective 
size  of  the  disk  cache.  Measure  unit  is  8kB.  Default  value  is  1000.  If  you  have 
enough  memory,  we  recommend  setting  this  parameter  to  25-50%  of  available 
RAM. 


WARNING:  For  FreeBSD,  kernel  recompilation  is  required  before  changing  memory 
usage  parameters  in  postgresqi. conf!  Read  Managing  Kernel  Resources, 
http://www.postqresql.Org/docs/7.4/interactive/kernel-resources.html,  in  PostgreSQL 
documentation. 


> To  reconfigure  Postgres  parameters: 

1 Stop  Postgres. 

2 Modify  the  ~postgres/data/postgresql . conf  file  (in  Parallels 
H-Sphere  2.5  and  up,  modify  its  custom  template  as  described  in 
Appendix  C of  Parallels  H-Sphere  Installation  Guide). 
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Here  is  an  example  of  PostgreSQL  configuration  for  a server  with  4 CPUs,  4GB 
RAM,  with  2.5  GB  database  dump  and  a separate  hard  drive  allocated  for 
transaction  logs: 

sort  mem  = 131072 

shared  buffers  = 262144 

max  connections  = 64 

wal  buffers=1000 

checkpoint  segments  = 9 

checkpoint  timeout  = 3600 

ef f ective_cache_size  = 100000 

3 Start  Postgres  and  make  sure  it's  working  properly.  If  parameters  are 
incorrect,  Postgres  might  not  start.  In  this  case,  please  also  set  the 
SHMALL  and  SHMMAX  kernel  parameters  according  to  the  rules 
described  in  the  RedHat  documentation  at 
http://www.redhat.com/docs/manuals/database/RHDB-2.1- 

Manual/admin  user/kernel-resou rces.html. 

4 Start  Postgres. 
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Moving  Transaction  Logs  to  a Separate  Hard  Drive 

If  the  system  database  is  large  (more  than  1G),  we  recommend  allocating  a separate 
hard  drive  for  its  transaction  logs.  It  is  especially  helpful  for  the  database  migration  or 
recovery  (on  page  440). 

> To  move  transaction  logs  to  another  hard  drive: 

1 Stop  Postgres. 

2 Mount  a new  hard  drive. 

3 Move  the  data/pg_xlog  directory  from  the  PostgreSQL  home 
directory  to  the  new  disk. 

4 Create  the  data/pg_xlog  symlink  to  the  new  location  in  place  of 
the  moved  directory. 

5 Start  Postgres. 
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Upgrading  Postgres  to  the  Latest  Version 

See  Upgrading  System  Database  (on  page  92). 

Troubleshooting 

Sometimes  while  importing  data  you  may  get  the  message  like  this: 

psql : data . db : 527 11 1 : ERROR:  copy:  line  422025,  Bad  float8  input  format 
--  underflow  psql : data . db : 527 1 1 1 : PQendcopy:  resetting  connection 

This  means  that  Postgres  cannot  interpret  data  it  has  just  exported. 

You  need  to  open  the  data.db  file: 

vi  data.db 

and  remove  the  line  which  number  is  calculated  in  the  example  above  as 
N=527iii  + 422025.  This  line  would  contain  a float8  number  like  1 .2e-318.  After 
removing  that  line,  you  need  to  recreate  and  reload  the  database. 


Changing  CP  URL 

This  section  tells  you  how  to  modify  the  URL  of  your  control  panel. 


In  this  section: 


Changing  IP  Address  to  Domain  Name  in  CP  URL 105 

Changing  Parallels  H-Sphere  Port 105 

Changing  Entire  CP  URL 106 

Setting  Multiple  Alternative  CP  URL's 107 
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Changing  IP  Address  to  Domain  Name  in  CP  URL 

Sometimes,  mostly  when  you  have  just  installed  Parallels  H-Sphere,  you  receive  the 
following  error  while  trying  to  access  your  Control  Panel  by  domain  name: 

Control  Panel  Error 

You  have  entered  invalid  control  panel  location.  Please  enter  your  account  login  and 
password. 

In  this  case,  you  need  to  change  your  hostname  to  your  CP  domain  name  instead  of 
the  IP  address: 

1 Log  into  your  CP  server  as  the  cpanel  user  (on  page  65). 

2 Edit  the  hsphere. properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 
In  the  cp_host  field,  enter  the  domain  name  instead  of  the  IP  address. 

Important:  If  you  changed  the  path_site_studio  variables  in 

~ cpanel/  shiva /pso  ft  con  fig/ hsphere  .properties  file  to  a domain  name, 
make  sure  to  change  IP  to  the  domain  name  in  all  SS  conf  files 

(/hsphere/  shared/ Site  Studio /pso  ft_conf  ig/). 

3 Restart  Parallels  H-Sphere  (on  page  54). 


Changing  Parallels  H-Sphere  Port 

By  default,  Parallels  H-Sphere  is  configured  to  use  port  8080,  and  it  is  not 
recommended  to  use  other  ports.  However,  if  you  still  need  to  change  the  port: 

1 Login  to  CP  server  as  the  cpanel  user  (on  page  65). 

2 Edit  ~ cpanel / shiva/ psof t_con fig/ hsphere . properties  : 

CP_PORT  = <CUSTOM_C P_PORT> 

DEFAULT_CP_PORT  = <CUSTOM_CP_PORT> 

If  you  are  running  Parallels  SiteStudio,  also  update  this  line: 

PATH_SITE_STUDIO  = Error!  Hyperlink  reference  not  valid. 

3 Edit  /hsphere / local /home / cpanel / apache /conf /httpd . conf 

as  described  in  Appendix  C of  Parallels  H-Sphere  Installation  Guide: 

Port  <CUSTOM_CP_PORT> 

4 If  you  are  running  Parallels  SiteStudio,  update  all  Parallels  SiteStudio 
configuration  files  that  are  located  in 

/hsphere /shared/ SiteStudio /pso ft  conf ig/ . 
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Changing  Entire  CP  URL 

Control  Panel  runs  on  the  Tomcat  servlet  engine  (on  page  66)  and  therefore  CP  URL 
pathname  configuration  differs  from  that  of  JServ  (on  page  58)  in  prevous  versions. 

A typical  Parallels  H-Sphere  control  panel  URL  looks  similar  to 

http : / / example . com: 8080/psoft/ servlet/psoft . hsphere .CP/ 

where: 

■ example . com  is  the  domain  name, 

■ psof t/serviet  is  the  mount  point, 

■ psof t. hsphere. cp  is  the  servlet  name. 

1 Login  to  CP  server  as  the  cpanel  user  (on  page  65). 

2 Edit  ~ cpanel / shiva/ psof t_conf ig/ hsphere .properties  to 

change  your  servlet  name  and  mount  point: 

# old  settings  --  commented  out 

# UPLOADER  URL  = /psoft/servlet/psoft . hsphere . Uploader 

# DOWNLOAD  URI  = /psoft/servlet/psoft . hsphere . Downloader 

# CP_URI  = /psoft/servlet/psoft . hsphere . CP 

# CLIENT_CP_URL  = psof t . hsphere . CP 

# new  settings 

UPLOADER  URL  = /cp/servlet/hsphere . Uploader 
DOWNLOAD  URI  = /cp/servlet/hsphere . Downloader 
CP  URI  = /cp/servlet/hsphere . CP 
CLIENT_CP_URL  = hsphere. CP 


Important:  To  avoid  problems,  please  check  that  the  same  servlet  name  and  mount 
point  are  set  in  all  these  parameters!  CP_URI  takes  the  precedence  otherwise. 

3  Logout  from  cpanel  back  to  root  and  run  the 

j akart a_servie t_upt  .pi  script  to  apply  the  new  servlet  name  and 
mount  point  to  the  Tomcat  configuration  files  (on  page  66)  and  to  the 
index  page  template  ~cpanei/ shiva/ shiva- 
templates/ index.html: 

cd  ~cpanel/shiva/psof t_config 
. / jakarta_servlet_upt .pi 

The  script  replaces  old  servlet  name  and  mount  point  in  the  following  files: 

~ cpanel /hsphere /WEB- INF /web . xml 
~cpanel/apache/ etc/mod_j  k . conf 
~ cpanel/ j akarta/ con f / server . xml 
~ cpanel/ shiva/ shiva- templates/ index . html 

Original  configuration  files  are  backed  up: 

~cpanel/hsphere/WEB-INF/web . xml . ORG 
~cpanel/apache/ etc/mod_j  k . conf . ORG 
''-cpanel/ j akarta/ conf/ server . xml . ORG 
~ cpanel/ shiva/ shiva-templates/ index . html . ORG 
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Important:  Don't  forget  to  run  this  script  after  the  Parallels  H-Sphere  update  to 
apply  your  CP  URL  customization  in  the  new  version! 

4 Restart  Parallels  H-Sphere  (on  page  54). 


Setting  Multiple  Alternative  CP  URL's 

> To  specify  several  alternative  CP  URL 's  for  main  Admin  CP: 

1 Log  into  your  CP  server  as  the  cpanel  user  (on  page  65). 

2 Enter  the  hsphere.  properties  file: 

vi  ~cpanel/ shiva/psof t_conf ig/hsphere .properties 

3 In  the  CP_HOST  field,  set  several  host  names  using  semicolon  as 
separator: 

CP_HOST=cp. testhost . com; cp. testhostl . com; 10.0.1.20 

4 Restart  Parallels  H-Sphere  (on  page  54). 
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Migrating  Control  Panel  Server 

By  server  migration  we  mean  moving  applications  and  data  from  one  server  to  another 
while  keeping  old  IPs  for  the  new  server. 


Note:  We  highly  recommend  performing  the  CP  server  migration  only  if  you  have 
practical  experience  with  Unix-based  systems.  We  will  not  be  responsible  for  the 
results  of  migration. 


It  is  not  recommended  to  erase  data  on  the  old  server  in  case  you  forget  to  move 
something  or  if  you  need  any  data  from  the  old  server.  It  is  safer  to  shut  down  the  old 
server  after  you  check  the  functionality  upon  migration. 

> To  perform  Control  Panel  server  migration: 

1 Install  Parallels  H-Sphere  Control  Panel  software  on  the  target  server 
(make  sure  to  use  the  same  Parallels  H-Sphere  version  that  is  running 
on  the  source  server). 

Note:  If  your  source  server  is  also  running  Site  Studio,  make  sure  to  install  Site 
Studio  on  the  target  server  as  well. 


2 Stop  Control  Panel  (on  page  54)  on  the  source  server. 

3 Move  the  following  directories  to  the  new  server: 


Directory 

Files 

/hsphere/ local /home/ cpa 
nel/shiva/psoft  config/ 

Parallels  H-Sphere  configuration  and 
properties  files 

/hsphere/ shared/ SiteStu 
dio/psoft  config/ 

Parallels  SiteStudio  configuration  and 
properties  files 

/hsphere /local /home/ cpa 
nel /apache/ etc/ 

Apache  configuration  and  properties 
files 

/hsphere /local /home/ cpa 
nel/ shiva/ shiva- 
t empl at es/ IMAGES 

Control  Panel  icons  and  images 

/hsphere /local /home/ cpa 
nel/ shiva/ custom 

Custom  Control  Panel  templates 

/hsphere/ shared/ SiteStu 
dio/var /websites 

Parallels  SiteStudio  user  data 

/var/lib/pgsql  (Linux) 
/var/db/pgsql  ( FreeBSD ) 

Parallels  H-Sphere  and  Parallels 
SiteStudio  system  databases  and 
database  settings  * 

/hsphere /local /home/ cpa 
nel/ . kb/ 

Parallels  H-Sphere  knowledge  bases 

/hsphere /local /home/ cpa 

Trouble  Ticket  system  attachments 
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nel/ . attachments/ 

/hsphere /local /home/ cpa 
nel/ shiva /packages 

Parallels  H-Sphere  Packages 

* Before  moving  postgresql  directory,  make  sure  to: 

1 . Stop  postgresql  service  on  the  source  and  target  servers. 

2.  Dump  Parallels  H-Sphere  and  Site  Studio  databases  on  the  source  server  and 
then  restore  them  on  the  target  server.  Use  our  documentation  (on  page  92)  for 
more  info. 


Note:  if  you  have  the  same  postgresql  version  on  the  source  and  target  server, 
move  this  directory  without  dumping. 

Alternatively,  use  rsync  to  move  necessary  data  to  the  new  server: 

rsync  -arlpogvzt  -e  ssh  $login@ $ip : $f older  $folder 
are  using  rsync  on  the  target  server 

if  you 

rsync  -arlpogvzt  -e  ssh  $folder  $login@ $ip : $f older 
are  using  rsync  on  the  source  server 

if  you 

Note:  $login  usually  is  root. 


4 Switch  IPs  between  the  old  and  new  servers. 

To  find  main  server  IP  in  Linux,  go  to: 

/ etc/ sysconf ig/ network- scripts/ if cf g-ethO 
To  find  main  server  IP  in  FreeBSD,  go  to: 

/etc/rc.conf 

Also,  please  make  sure  that  main  server  IPs  are  excluded  from  the 
/hsphere/ local /network/ IPs  file  (corresponding  IP  on  the  corresponding 
server). 

5 Prevent  the  startup  of  Control  Panel  service  on  the  source  server  on 
reboot: 

For  Linux,  run: 

chkconfig  --level2345  httpdcp  off 
For  FreeBSD,  run: 

chmod  000  /usr/local/etc/rc . d/apachecp . sh 

6 Reboot  both  servers  and  the  router.  Router  reboot  is  needed  to  clear 
ARP  cache.  You  can  also  do  it  using  other  methods. 

7 Check  the  Control  Panel  functionality. 

If  you  want  to  perform  Server/IP  migration,  skip  steps  4-6  and  follow  the  instruction  on 
Changing  IPs  (on  page  40)  instead. 
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Generating  SSH  Keys  for  Parallels  H- 
Sphere  Servers 

Parallels  H-Sphere  Control  Panel  interacts  with  its  Unix-based  servers  via  SSH 
protocol.  For  user  to  have  permanent  access  to  Parallels  H-Sphere  remote  servers  and 
to  log  into  them  automatically  without  entering  password  each  time,  the  SSH  public 
keys  for  the  cpanel  user  on  the  CP  box  should  be  copied  and  added  to  each  Unix  box 
in  Parallels  H-Sphere  cluster. 

Normally,  Parallels  H-Sphere  does  this  automatically  during  installation.  However, 
sometimes  there  is  a need  to  regenerate  or  restore  SSH  keys.  This  document  will  guide 
you  through  the  process  of  generating  SSH  keys  on  the  CP  box  and  adding  them  to 
each  Parallels  H-Sphere  server. 

> To  generate  SSH  keys: 

1 Enter  the  CP  box  as  the  cpanel  user  (on  page  65). 

2 Check  if  you  have  SSH  public  keys  generated  for  the  cpanel  user. 

RSA: 

$ cat  ~cpanel/ . ssh/ identity .pub 
DSA: 

$ cat  ~cpanel/ . ssh/id_dsa .pub 

3 If  any  of  these  files  does  not  exist,  generate  missing  SSH  key  for  the 
cpanel  user  by  the  corresponding  command  (passphrases  must  be 
empty): 

RSA: 

$ ssh-keygen  -t  rsal 
DSA: 

$ ssh-keygen  -d 

4 Place  the  public  SSH  keys  of  the  CP  server's  cpanel  user  into  the 
corresponding  files  in  the  /root/  . ssh  folder  on  each  Parallels  H- 
Sphere  box: 

1 . Log  into  an  Parallels  H-Sphere  box  as  root. 

2.  Create  the  authentication  key  files  for  root  if  they  don't  exist: 

RSA: 

# touch  /root/ . ssh/authorized_keys 

DSA: 

# touch  /root/ . ssh/authorized_keys2 
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3.  Insert  the  RSA  key  from  the  -cpanei/ . ssh/identity.pub  file  on  the  CP 
server  into  /root/ . ssh/authorized  keys  on  this  box, 
and  the  DSA  key  from  ~cpanei/ . ssh/ id  dsa . pub  into 

/ root/  . ssh/authorized_keys2,  respectively. 


Encrypting  Trouble  Tickets 

PGP  encryption  mechanism  is  implemented  in  Parallels  H-Sphere  trouble  ticket  system 
to  encode  and  decode  secure  parts  of  TT  messages. 

PGP  encryption  is  implemented  on  the  basis  of  the  Cryptix  package 
(http://www.crvptix.org/products/openpqp/index.html).  Cryptix  is  a Java  implementation 
for  OpenPGP  (http://www.ietf.org/html.charters/openpqp-charter.html).  Cryptix  jar  files 
should  be  located  in  the  ~cpanei/java_rt  directory  and  their  names  should  be 
included  into  CLASSPATH: 

cryptix- j ce -provider . jar 
cryptix-message-api . j ar 
cryptix-openpgp -provider . jar 
cryptix-pki-api . j ar 
cryptix32 . j ar 


In  this  section: 


Generating  PGP  Public  Key  and  PGP  Private  Key 1 1 1 

Enabling  PGP  Encryption  In  Your  Support  Center 1 1 2 

Encrypting  Texts  With  PGP  Public  Key 112 

Using  Encrypted  Parts  in  T rouble  Tickets 1 1 2 


Generating  PGP  Public  Key  and  PGP  Private  Key 

To  generate  a pair  of  PGP  public  and  private  keys,  use  any  PGP  encryption  program. 

Or,  you  may  use  the  KeyPairGenerator  Java  tool  integrated  into  Parallels  H-Sphere: 

j ava  psof t . hsphere .tools . KeyPairGenerator 
-i  "This  is  a main  identification  string" 

-s  "identification  string  for  subkey" 

-e  "PGP  Code  Phrase" 

-prf  "/path/PGP_Private  Key/file" 

-pcf  " /path/to/PGP  Public  Key/file" 
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Enabling  PGP  Encryption  In  Your  Support  Center 

Set  PGP  Private  Key  and  PGP  Code  Phrase  in  the  Settings/Tech  Support  menu  in  the  admin 
panel  to  be  able  to  decode  encrypted  texts  directly  from  TT  Administration  Center. 

Encrypting  Texts  With  PGP  Public  Key 

PGP  Public  Key  should  be  made  available  to  customers  to  encrypt  their  messages. 

Information  may  be  encrypted  by  means  of  the  PGPEncrypter  Java  tool  in  Parallels  hl- 
Sphere: 

j ava  psof t . h sphere .tools . PGPEncrypter 
-m  "This  is  a message  to  encrypt" 

-f  "This  is  a file  where  encrypted  phrase  will  be  saved" 

-k  "/path/to/PGP  Public  Key/file" 

Using  Encrypted  Parts  in  Trouble  Tickets 

The  following  example  represents  the  completely  formed  message  with  encrypted 
information: 

information  is  beyond  BEGIN  PGP  MESSAGE 

Version:  Cryptix  OpenPGP  0.20030205 

hQEOA/ d04g5f FsnOEAP+LZ+xiV66LWcK/ xoRd7aFvUiSn JOZD57hiuACvccPPc2A 
eOFELnqdnOcbabXbsG7W7Yf YCYfGQzqesOeTf xoO/EXOtB9WGHZ45pZfBYRJC517 
F401fgO+KES511/oEaGgy7  7 j zSPAYfsYDOYnrKW2f01dIBAk37MnjY4Uk+0  9I6oD 
/ 3FJxlEF4p2G41ZltAFJAHAdgNlTivZQ3cJ24fTd0sFzRbuo2GeirF7 jC35R17hN 
vDwCnqNWIPMpHrs4uAOOsvD/nKSDML+LIPCoK9YUr+NKj lECUyXIAzfNKOOo8nyN 
f oNzqe3zf Y0 14  8yL0gYtDrKR8SPa+ILQv/ 30Ke71rlYdpCo9H+U4dLUBNRLkNveK 
Ls9MyuleAd20MOHlmOmxAMGEK2avjHjOdU+PDi8= 

=f  Hh9 

END  PGP  MESSAGE the  invisible 

In  the  CP  trouble  ticket  center  this  message  will  be  displayed  as: 

information  is  beyond BEGIN  PGP  MESSAGE secure  information 

END  PGP  MESSAGE the  invisible. 

In  order  to  read  the  encrypted  information,  click  on  the  link  Click  here  to  access 
encrypted  information.  Decrypted  information  would  appear  in  a separate  window. 

The  ticket's  encrypted  part  would  not  be  revealed  in  the  reply  message  received  by  the 
customer: 


Control  Panel  Server  113 


========  CUT  HERE  ========= 

Your  support  request  was  answered: 

Created:  Feb  11,  2004  3:27:45  PM 
Last  Mod:  Feb  11,  2004  3:28:02  PM 

Assigned  To:  admin (Admin  Accountl) 


[Feb  11,  2004  3:28:46  PM] 
A:  Hello 


[Feb  11,  2004  3:27:45  PM] 

Q:  information  is  beyond  | secure  information  | the  invisible. 

To  learn  more  about  encrypted  messages  in  trouble  tickets,  please  refer  to  the 
Providing  Customer  Support  documentation  in  Parallels  H-Sphere  Service 
Administrator  Guide. 


Customizing  Domain  Registration  Lookup 
Script 


Custom  domain  registration  lookup  script  is 

/hsphere/ shared/ scripts/ custom_reg.  H-Sphere  uses  the  whois  command  to 
figure  out  whether  domain  is  already  registered  or  not.  Different  domain  registration 
servers  respond  in  different  way,  so  it  is  almost  impossible  to  keep  the  script  up-to-date 
to  properly  support  all  potential  TLD's. 


In  H-Sphere  3.2  we  introduce  the  built-in  /hsphere/ shared/ scripts/ custom  reg 
with  a minimal  code.  Instead,  H-Sphere  system  administrator  will  be  able  to  create  and 
Customize  the  /hsphere/ shared/ scripts/pkg_scripts/ custom_reg  script.  H- 
Sphere  will  check  if  the  latter  script  exists  and  thus  invoke  it. 


Here  is  an  example  of  the  script: 

# ! /bin/sh 

free  domain_pattern="No  match  for" 


free  domain_pattern="Status : \s*FREE" 

= * .mobi  ] ] ; then 
free  domain_pattern="NOT  FOUND" 

= * . nl  ] ] ; then 
free  domain_pattern="is  free" 

= * . it  ] ] ; then 

free  domain_pattern="Status : \s*AVAILABLE" 

= * . uk  ] ] ; then 

free  domain_pattern="This  domain  name  has  not  been  registered.' 
= * . eu  ] ] ; then 

free  domain  pattern="Status : \s*FREE" 


if  [ 

[ $1 

fi 

if  [ 

[ $1 

fi 

if  [ 

[ $1 

-H  4-1 

4-t  -H 

[ $1 

fi 

if  [ 

[ $1 

fi 

if  [ 

[ $1 
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fi 

if  [[  $1  = * . name  ]];  then 

free  domain_pattern="No  match." 
f i 

whois  $1  | grep  "$free  domain  pattern"  2>&1  >/dev/null; 


echo  $? 
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Web  Server 

This  chapter  instructs  you  on  some  task  you  may  need  to  perform  on  Parallels  H- 
Sphere  Unix  Web  server. 

In  this  chapter: 

Understanding  Web  Server  Configuration 116 

Preventing  Manipulation  with  Logs  Directory  Permissions 131 

Altering  Virtual  Host  Configuration 131 

Calculating  Web  T raffic 133 

Adding  Directories  for  User  Homes 136 

Installing  Ruby  on  Rails 1 36 

Installing  ChiliiSoft  ASP 137 

Installing  mod_perl 145 

Installing  Zend  Optimizer 1 46 
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Understanding  Web  Server  Configuration 

The  following  software  is  installed  on  Parallels  H-Sphere  Unix  Web  boxes: 

Core  services: 

■ Apache  Web  Server:  support  of  Apache  1 .3.x  and  2.2.x.  PHP  comes  as  separate 
packages. 

■ ProFTPd  FTP  Server  (on  page  1 1 7) 

Additional  software: 

■ SSL  support:  OpenSSL  (on  page  121) 

■ PPIP  (on  page  386): 

■ PPIP  4 - all  supported  Parallels  Pi-Sphere  versions; 

■ PPIP  5 - Parallels  Pi-Sphere  2.5  and  up. 

■ Perl  (on  page  371) 

■ Third-party  log  analyzers  (on  page  122)  (Web  statistics  calculators): 

■ Webalizer,  ModLogAn,  AWStats  - included  into  Parallels  Pi-Sphere  default 
installation 

■ Urchin  v.3.xx,  4.xx,  5.xx  - supported  but  not  included  to  the  installation 

■ Webshell  (on  page  126)  - Parallels  Pi-Sphere  integrated  Web  directory  file  manager 

■ MnoGoSearch  (on  page  127)  - search  engine  that  indexes  websites  by  keywords 

■ Jail  (on  page  129)  - chrooted  shell  environment  with  a set  of  widely  used  utilities 
and  file  managers 

Security  schemes: 

■ Webbox  security  scheme  (on  page  131)  - preventing  manipulation  with  logs 
directory  permissions. 


In  this  section: 


FTP  Server 117 

SSL  Implementation  on  Unix  Web  Servers 121 

Third  Party  Log  Analyzers  Integrated  in  Parallels  H-Sphere 122 

WebShell 126 

MnoGoSearch 127 

Parallels  H-Sphere  Jail 1 29 
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FTP  Server 

Parallels  H-Sphere  FTP  is  based  on  ProFTPd  server  and  installed  on  Web  boxes  as 
hsphere-ftp-<vers/or?>-<bu/7cf>  package,  where  <version>  is  ProFTPd  version,  and  <build> 
is  this  package's  build  number. 

ProFTPd  binary  is  /hsphere/ shared/ sbin/proftpd. 

Please  refer  to  the  original  ProFTPd  site  for  Configuration  Directive  List, 
http://www.proftpd.orq/docs/directives/linked/confiquration.html. 

There  are  two  kinds  of  FTP: 

■ User  FTP:  When  a new  user  account  is  created,  its  user  is  provided  with  the  FTP 
account  and  thus  may  download/upload  files  from/to  the  user's  home  directory 
(/hsphere /local /home / <user_name>)  by  FTP  using  its  name  and  password. 

■ Virtual  (anonymous)  FTP:  a service  provided  only  for  dedicated  IP  accounts, 
enables  to  create  virtual  accounts  to  download/upload  files  from/to  virtual  account 
directories  that  are  located  within  the  account  home  directory,  and  provides 
anonymous  access  to  the  public  directory. 


In  this  section: 


User  FTP 118 

Virtual  FTP 119 

FTP  Over  SSL/TLS 120 
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User  FTP 

Log  File 

When  a user  uploads  or  downloads  data,  the  corresponding  record  is  made  in  the  log 
files: 

/hsphere/local/var/prof tpd/xf erlog - FTP  log 
/hsphere/local/var/ prof  tpd/ tls  . log  - TLS/SSL  log 

Configuration 

/hsphere/ shared/ conf  ig/ f tpd  - FTP  configuration  directory 

/hsphere/ shared/ config/ ftpd/proftpd.  conf  - FTP  configuration  file 

/hsphere/  shared/ con  fig/ ftpd/proftpd  .conf. shared  - FTP  subaccounts' 
configuration  file 

/hsphere/local/ config/ f tpd/lservers/web  <Shared_IP>  . conf  - configuration 
files  of  logical  servers'  vitrual  hosts 

/hsphere/local/ config/ f tpd/ sites  - users'  vitrual  hosts 

Read  how  to  make  changes  into  FTP  config  files  in  Appendix  C.  Customizing  Server 
Configuration  Files  of  Parallels  H-Sphere  Installation  Guide. 

Download/Upload  Permissions 

Users  can  download  and  upload  files  from  his  document  root  directory 
(/hsphere /local /home / <user_name>  / <domain_name>)  after  they  log  in  by  FTP 
entering  their  login  name  (<user_name>)  and  password: 

ftp  user_name@domain_name 


User  FTP  Traffic  Calculation 

Cron  (on  page  33)  runs  the 

/hsphere/ shared/ scripts/ cron/ f tp_anlz_user . pi  script  On  everyday  basis 
for  collecting  user  FTP  traffic. 

ftp  anlz  user . pi  parses  the /hsphere/local/var/prof tpd/xf erlog  FTP 

log  file  and  writes  FTP  traffic  statistics  into  the 

/hsphere/local/var/ statistic/ dd .mm.  YYYY  . gst . txt  Statistics  files. 
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The  TrafficLoader  (on  page  36)  Java  class  utility  is  launched  by  cron  to  process  FTP 
traffic  statistics  and  load  it  to  the  system  database.  TrafficLoader  also  calls  the 

/hsphere/ shared/ scripts/xfer_cat . pi  to  gzip  outdated  statistics  files  and 
move  them  into  the  loaded  directory  where  they  are  stored  as 

dd.  mm . YYYY . gst . txt . gz  archives. 

Virtual  FTP 

Log  File 

For  each  virtual  account,  its  own  configuration  file  is  located  in  the 

/hsphere /local/var/  prof  tpd/ logs  / directory.  File  format:  <vhost_id> . ftp . log. 

For  example,  wwwuser  has  virtual  FTP  enabled  for  the  test  .psoft  virtual  host,  and 
vhost_id=l2 08  is  the  virtual  host  identifier.  When  the  virtual  FTP  user  test3  connects 
by  FTP  to  the  virtual  host  (ftp  test3@test . psoft),  he  would  be  allowed  to 
download  and  upload  (if  permissions  to  write  are  set  to  that  virtual  host)  from 

/hsphere/iocai/home/wwwuser/1208  directory  for  downloads  and 
/hsphere/local/home/wwwuser/1208/ incoming  directory  for  uploaded  files. 

The  log  records  would  be  added  to 

/hsphere /local/var/proftpd/logs/1208 . ftp. log 

The  same  is  true  for  anonymous  FTP  account.  If  this  option  is  enabled  for  the  test.psoft 
virtual  host,  any  user  may  connect  by  FTP  using  anonymous  login  and  any  email  as  a 
password,  and  all  his  downloads  would  go  to 

/hsphere/local/home/wwwuser/1208  directory,  uploads  to  the 
/hsphere/local/home/wwwuser/1208/ incoming  subdirectory. 


Configuration 


Configuration  directory  is  /hsphere/iocai/config/ftpd. 

The  sites  subdirectory  contains  configuration  files  <vhost_id> . conf.  These  files  are 
generat  ed  by  Parallels  H-Sphere  when  the  new  virtual  FTP  server  is  created,  by 
parsing  the  /hsphere/local/home/cpanel/shiva/shiva- 
tempiates /common/ ftp/ ftp . conf  ig  template  where  the  structure  of  virtual  host 
configuration  is  set. 

The  sites/ index . conf  file  contains  the  inclusions  of  the  <vhost_id> . conf  files. 
The  sites/<v/josf_/cf>.passwd  files  contain  information  on  the  following  accounts: 

- <web_user_name>  - name  of  the  web  user  under  which  account  this  virtual  host  is 
enabled.  Thus,  user  may  log  on  by  his  name  and  password  to  connect  by  FTP  to  the 
virtual  host  FTP  directory. 

- <anonymous>  - if  anonymous  FTP  is  switched  on,  anonymous  connection  may  be 
installed  by  the  outsider. 

- the  list  of  virtual  FTP  users  with  their  base64-encoded  passwords. 
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/hsphere/iocai/conf  ig/ ftpd/proftpd.  conf  - configuration  file.  It  includes  the 
user  FTP  configuration  file  and  sites/index . conf  file. 


Virtual  FTP  Traffic  Calculation 


Cron  (on  page  33)  runs  the  /hsphere/ shared/ scripts/ cron/ f tp_anlz  . pi 

script  daily  to  collect  virtual  FTP  traffic  statistics. 

The  script  parses  the  virtual  FTP  log  files  and  writes  traffic  statistics  into  the  timestamp- 
named  /hsphere/local/var/ statistic/dd.mm.  YYYY  . ftp  . txt  Statistics  files. 

The  TrafficLoader  (on  page  36)  Java  class  utility  is  launched  by  cron  to  process 
anonymous  FTP  traffic  statistics  and  load  it  to  the  system  database.  TrafficLoader  also 
calls  the  /hsphere/ shared/ scripts/xf er_cat . pi  to  gzip  outdated  statistics  files 
and  move  them  into  the  loaded  directory  where  they  are  stored  as 

dd . mm . YYYY . f tp . txt . gz  archives. 

FTP  Over  SSL/TLS 


Parallels  H-Sphere  3.1  implements  FTP  over  SSL/TLS  by  adding  mod_tls  module 
(http://www.castaalia.ora/proftpd/doc/contrib/ProFTPD-mini-HOWTO-TLS.html).  If  client 
software  supports  TLS,  encryption  is  used,  if  not  - FTP  client  operates  in  ordinary 
mode. 

FTP  over  SSL/TLS  works  with  shared  SSL  certificates  (on  page  121)  on  standard  FTP 
ports  (20/21). 

The  /hsphere /local/  config/ ftpd/ script  s/ftp-sharedssl.sh  script  which 
runs  after  installing  the  FTP  software  creates  virtual  configs  from  the 
/hsphere/iocal/ config/ f tpd/isrv . conf . tmpi  template  for  each  shared  IP  - 
/hsphere/local/conf  ig/ f tpd/lservers/web  <Shared_IP>  . conf  that  take 
proftpd  configuration  from  the  lservers  directory. 

f tp-sharedssi . sh  script  runs  also  after  each  restarting  of  the  FTP  server,  and  all 
virtual  hosts  are  regenerated  anew. 

Please  refer  to  FTP  client  software  which  support  FTP  over  SSL: 

■ http://www.ford-hutchinson.eom/~fh-1-pfh/ftps-ext.html#client 

■ http://hp.vector.co.ip/authors/VA027031/orenosv/ftps.html 

■ http://www.vicman.net/lib/ftps/client 
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SSL  Implementation  on  Unix  Web  Servers 

This  document  covers  SSL  implementation  on  Parallels  H-Sphere  Unix  Web  servers. 

SSL  is  implemented  by  the  mod_ssi  Apache  utility  and  uses  OpenSSL  package 
installed  on  the  box.  Parallels  H-Sphere  uses  native  OpenSSL  packages  installed  with 
operating  systems. 

There  are  two  SSL  modes:  dedicated  and  shared. 


Dedicated  SSL 

In  dedicated  SSL  mode,  a single  SSL  certificate  is  issued  for  a dedicated  IP. 
For  dedicated  IPs,  SSL  keys  are  located  in  the  user  home  directory: 

/hsphere/ local /home/ <user_name> / ssl . conf/<domain_name>/ 

If  SSL  is  enabled,  the  following  files  will  be  placed  to  this  directory: 

■ server,  crt  - SSL  certificate 

■ server . key  - SSL  private  key 


Shared  SSL 


In  shared  SSL  mode,  one  SSL  certificate  would  be  used  for  all  IPs  under  the  same 
domain  zone. 

Directories  with  SSL  certificates  and  keys  are  located  in  the  Apache  config  directory 

(/hsphere/ shared/ apache/ config/). 

/hsphere/ shared/ apache/ conf  / ssl . shared  - directory  for  shared  SSL 
certificates  and  keys. 

Shared  SSL  directory  structure: 

■ ss\.shared/<domain_name>  - directory  with  SSL  certificate  and  private  key  for  a 
domain 

With  SSL  enabled,  the  following  files  are  placed  into  this  directory: 

■ server . crt - SSL  Certificate 

■ server . key  - SSL  Private  Key 

■ server . csr  - SSL  signing  request  (if  certificate  has  been  generated  by  Parallels 
Fl-Sphere  SSL  generator  tool) 

When  the  user  turns  SSL  off,  the  files  remain  on  the  server.  When  the  user  turns  SSL 
back  on,  they  are  overwritten  with  the  new  files. 
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Third  Party  Log  Analyzers  Integrated  in  Parallels  H- 
Sphere 

Parallels  H-Sphere  integrates  the  following  third-party  log  analyzers  (traffic  calculators): 

■ Webalizer 

■ ModLogAn 

■ AWStats 

■ Urchin 

Please  also  refer  to  Web  Traffic  Calculation  in  Parallels  H-Sphere  (on  page  133). 


In  this  section: 


Webalizer 123 

ModLogAn 124 

AWStats 125 

Urchin 125 
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Webalizer 

Webalizer  (http://www.webalizer.com/)  is  one  of  the  most  popular  traffic  log  analyzers. 

It  is  included  to  default  Parallels  H-Sphere  installation  and  available  for  Linux-hosted 
accounts.  Webalizer  analyzes  transfer  log  and  generates  readable  HTTP  transfer 
reports  for  a domain. 

To  activate  the  Webalizer  resource,  the  Transfer  Log  resource  must  be  enabled. 

Webalizer  is  installed  as  the  hsphere-webalizer ~<version>-<build>  package,  where 
<version>  is  Webalizer  version,  and  <build>  is  this  package's  build  number. 

/hsphere/ shared/bin/webalizer  - Webalizer  installation  directory. 

/hsphere/ shared/ apache /conf /webalizer  user.cfg  - Webalizer  COnfig  file. 

In  Parallels  H-Sphere  scripts  directory,  the  following  scripts  are  used  for  Webalizer 
activation  and  update: 

■ /hsphere/ shared/ scripts/webalizer-init  - script  for  Starting  Webalizer 

■ /hsphere/ shared/ scripts/webalizer-stop  - Stop  Webalizer 

■ /hsphere/shared/scripts/webalizer-update  . pi  - Perl  script  for 
Webalizer  update 

Webalizer  directory  for  a domain: 

/Usphere/\oca\/home/<uset>/<domain.name>/wehaiizer/. 

Webalizer  statistics  for  a domain  can  be  viewed  at  Error!  Hyperlink  reference 
not  valid. 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
133). 
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ModLogAn 

ModLogAn,  http://www.modloaan.org/,  is  a third-party  traffic  calculation  utility,  similar  to 
Webalizer. 

To  activate  the  ModLogAn  resource,  Transfer  Log  must  be  enabled. 

ModLogAn  is  installed  as  the  hsphere-modiogan-<version>-<build>  package,  where 
<version>  is  ModLogAn  version,  and  <build>  is  this  package's  build  number. 

/hsphere/shared/bin/modlogan  - ModLogAn  installation  directory. 

/hsphere/ shared/apache/conf /modlogan  user  . cfg  - ModLogAn  COnfig  file. 

In  the  Parallels  H-Sphere  scripts  directory,  the  following  scripts  are  used  for  ModLogAn 
activation  and  update: 

■ /hsphere/shared/ scripts/modlogan-init  - script  for  ModLogAn 
initialization. 

■ /hsphere/ shared/ scripts/modlogan-stop - Stop  ModLogAn 

■ /hsphere/ shared/ scripts/modlogan-update  .pi  - Perl  script  for  ModLogAn 
update 

ModLogAn  directory  for  a domain: 

/hsphere/local/home/<user>/ <domain.name>/ modlogan/. 

ModLogAn  statistics  for  a domain  can  be  viewed  at  Error!  Hyperlink  reference 
not  valid. 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
133). 
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AWStats 


AWStats  is  a free  tool  that  generates  advanced  graphical  web  server  statistics  reports. 
AWStats  is  set  up  on  each  Unix/Linux  and  Windows  web  server  with  Parallels  H- 
Sphere  installation  or  upgrade.  Statistics  is  calculated  for  each  domain  separately. 

AWStats  is  installed  as  the  hsphere-awstats-<vers/on>-<bu/7d>  package,  where 
<version>  is  AWStats  version,  and  <build>  is  this  package's  build  number. 

AWStats  installation  directory:  /hsphere/shared/awstats. 

Each  domain  has  its  own  AWStats  configuration  file: 

/hsphere/local/home/<user>/ <domain.name>  / cgi- 
bin/awstats  . <domain.name> . conf 

AWStats  log  directory  for  a domain: 

/hsphere/local/home/<user>/ <domain.  name>/ awstats/ data/ 

AWStats  statistics  for  a domain  can  be  viewed  at  Error!  Hyperlink  reference 
not  valid. 

For  the  location  of  user  log  files,  please  refer  to  Third-Party  Traffic  Calculation  (on  page 
133). 

Urchin 

Urchin  is  a third  party  Web  analytics  software  integrated  into  Parallels  Fl-Sphere.  Urchin 
is  installed  and  configured  separately  (on  page  461). 

Urchin  directory:  /hsphere/local/urchin. 


Urchin  collects  statistics  for  each  domain  into  the 

/hsphere/  local  /ur  chin  /var/  logs  /urch±n-<domain_id>  .log  files.  This 
statistics  is  transferred  to  the  Urchin  remote  server  via  PITTP  by  means  of  the  print- 
log,  pi  script  located  in  cgi-bin  directory  of  each  domain  directory. 

Log  file  with  Urchin  history:  /hsphere/local/urchin/data/history. 
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WebShell 


WebShell  is  the  Parallels  H-Sphere  web-based  file  manager  that  enables  to  browse, 
access,  and  protect  remote  directories  without  knowing  the  Unix  file  structure.  It  allows 
to  copy,  move,  delete,  and  rename  files  and  directories  in  the  home  directory  on  the 
server.  Also,  it  can  be  used  to  upload,  download,  compress  and  decompress  files  as 
well  as  preview  them  in  the  browser. 

WebShell  is  installed  with  Web  server  by  means  of  hsphere-websheii  package, 
/hsphere/ shared/ apache/htdocs/webshell4  - WebShell  4 installation  directory. 


In  this  section: 
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WebShell  CGI  Mode 


Regular  WebShell  (SO  mode)  requires  that  certain  modules  (exec,  proc_open,  and 
some  others)  are  enabled  in  php.ini.  However,  more  restricted  security  schemes  have 
these  modules  disabled.  In  this  case,  WebShell  CGI  mode  is  developed  to  work  in 
standalone  PHP  environment. 

WebShell  CGI  mode  package  is  hsphere-websheii-cgi. 

/hsphere/ shared/ apache/htdocs/webshell5  - WebShell  CGI  directory. 

> To  switch  to  WebShell  CGI  mode: 

1 Go  to  admin  CP,  E. Manager ->  Servers ->  L.Servers  menu. 

2 Choose  WebShell5  (CGI  Mode)  option  in  Additional  Options. 

After  that,  WebShell  in  CGI  mode  will  be  available  for  a virtual  host  at:  Error ! 
Hyperlink  reference  not  valid. 

Specific  WebShell  CGI  Mode  features: 

■ User  authentication  procedure  uses  unixserver  daemon  (based  on  daemontools) 
with  pwgetquota  utility 

■ pwgetquota  utility:  returns  user  quota  limits  and  login  status 

■ standalone  PHP  instructions  are  added  to  the  .htaccess  file  in  the  websheii5 
directory  and  to  Apache's  httpd.conf 
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MnoGoSearch 

MnoGoSearch,  http://www.mnoqosearch.org/,  is  a web  search  engine  that  searches 
your  site  by  keywords.  It  can  run  on  both  intranet  and  Internet  pages.  MnoGoSearch  is 
installed  into  Parallels  H-Sphere  from  a single  package  hsphere-mnogosearch- 
<version>-<build>,  where  <version>  is  MnoGoSearch  version,  and  <build>  is  this 
package's  build  number. 

All  MnoGoSearch  files  are  installed  in  /hsphere/shared/mnogosearch,  except  for 

mnogosearch-init  and  mnogosearch-set  scripts,  that  are  placed  to 
/hsphere/ shared/ scripts. 

For  the  proper  work  of  MnoGoSearch,  you  will  also  need  the  file 

~httpd/ conf /mnogosearch . conf  that  assigns  domains  but  is  not  included  in  the 

package  hsphere-mnogosearch-x . x . x. 


In  this  section: 
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MnoGoSearch  Configuration  Scripts 

mnogosearch-init 

mnogosearch-init  script  is  used  to  enable/disable  MnoGoSearch. 

Usage: 

mnogosearch-init  [ -f  homedir  ] [ -u  login  ] [ -g  group  ] [ -d  domain  ] 

[ -1  dblogin  ] [ -p  dbpasswd  ] [ -t  dbhost  ] [ -n  dbname  ] [ -a 

user_action  ] 

Where: 

■ homedir  - user  home  directory 

■ login  - user  name 

■ group  - the  group  to  which  the  user  belongs 

■ domain  - domain  name 

■ dblogin  - MnoGoSearch  database  login 

■ dbpasswd  - MnoGoSearch  database  password 

■ dbhost  - MnoGoSearch  database  host 

■ dbname  - MnoGoSearch  database  name 

user_action  - 'set'  parameter  adds  MnoGoSearch,  'drop'  removes  When 
MnoGoSearch  is  being  enabled,  this  script: 
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■ Creates  for  the  domain  folder /user  homedir/mnogosearch/domain  name 

where  it  places  the  files  indexer . conf  and  search . htm.  A user  can  configure 
these  files  to  customize  indexer  and  frontend. 

■ in  the  folder /user  homedir/domain  name,  creates  the  folder 

f e_mnogosearch  where  it  places  PHP-frontend.  Now,  the  MnoGoSearch  can  be 
found  at  Error ! Hyperlink  reference  not  valid. 

■ creates  the  table  structures  by  running: 

/hsphere/ shared/mnogosearch/ sbin/ indexer  -Ecreate 
user  homedir/mnogosearch/domain  name/indexer . conf 

■ performs  indexing. 

When  MnoGoSearch  is  being  disabled,  the  mnogosearch-init  script  removes  all  the 
custom  settings. 

mnogosearch-set 

mnogosearch-set  script  is  used  to  add/remove  startup  links  from  the  server. 

Usage: 

mnogosearch-set  [ -a  | -r  ] [ -d  domain  ] [ -u  URL  ] 

Where: 

■ -a  - adds  startup  URL 

■ -r  - removes  existing  entering  URL 

■ domain  - domain  for  which  these  changes  are  done 

■ URL  - URL  which  is  to  be  added  or  removed  This  script  is  executed  when  the 
startup  link  in  the  field  "Add  new  MnoGoSearch  URL"  is  submitted.  It  adds/removes 
the  startup  URLs  into/from  the  file 

user  homedir/mnogosearch/domain  name/indexer . conf 


MnoGoSearch  frontend 

MnoGoSearch  frontend  written  in  Perl  is  replaced  with  PHP-based  frontend. 

To  use  MnoGoSearch  with  PHP  frontend,  PHP  must  include  mnogosearch-php- 
extension.  See  Parallels  H-Sphere  PHP  (on  page  386)  documentation. 
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Parallels  H-Sphere  Jail 

Parallels  H-Sphere  jail  shell  provides  chrooted  shell  environment  with  a set  of  widely 
used  utilities  and  file  managers.  It  is  implemented  via  hsphere-jaii-<vers/'on> 
package. 

If  the  corresponding  resource  is  enabled  for  the  account,  user's  SSH  access  is  realised 
in  the  chrooted  enviroment  limited  by  the  user  home  directory. 

During  jail  execution  by  the  SSHD  daemon  the  formed  jail  skeletons  are  bound  to  the 
corresponding  mount  points  in  the  user's  home.  For  this  purpose  jaild  daemon  is 
used,  which  communicates  with  jail  client  via  a UNIX  socket.  If  none  ssh  connections 
are  established  by  unix  user,  the  mount  points  become  unmounted  by  the  related  cron 
task  during  next  2 minutes. 

In  this  section: 
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File  Managers 129 

Scripts 130 


Utilities 

hsphere- j ail  package  includes  a set  of  the  following  widely  used  utilities:  cat,  echo, 
In,  mkdir,  ps,  rm,  sh,  cp,  date,  kill,  Is,  mv,  pwd,  rmdir,  sleep,  md5/md5sum,  ping,  awk, 
diff,  find,  id,  sed,  tar,  whereis,  basename,  dirname,  grep,  Idd,  sort,  touch,  which,  cut,  du, 
head,  more,  tail,  vi,  whoami,  clear. 

These  utilities  with  the  corresponding  list  of  required  libraries  and  share  configuration 
directories/dbs  are  formed  in  the  predefined  location  during  package  install  and  may  be 
recreated  in  the  case  of  system  update  via  native  package  managers. 


File  Managers 

The  following  widely  used  file  managers  are  available: 

■ me  (http://www.ibiblio.org/mc)  - GNU  Midnight  Commander 

■ ytree  (http://www.han.de/~werner/ytree.html)  - Ytree  a UNIX  Filemanager 

■ vifm  (http://vifm.sourceforge.net/)  - ViFM  a UNIX  Filemanager 
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Scripts 

List  of  the  included  scripts  follows: 

■ /hsphere/local/conf ig/ j ail/scripts/check  j ail  Checks  whether 
utilities  and  their  libraries,  which  are  included  in  the  jail  environment,  were  changed 
(for  example  after  system  update).  If  so,  the 

/hsphere/ local/ conf ig/ jail/ scripts/ conf ig_j ail  is  executed. 

■ /hsphere/local/conf ig/ j ail/scripts/config  jail  is  used  for  forming 
jail  environment  and  executed  in  the  post-install  package  section  or  via  the 

/hsphere /local/  conf  ig/ jail/  scripts/  check_j  ail  script. 

■ /hsphere /local/  conf  ig/ jail/  scripts/  j ailmount  is  a realization  of  jaild 
daemon  which  accepts  connection  from  the  jail  client  when  establishing  ssh 
connection.  It  requires  daemon  tools  and  unixserver  installed  on  the  boxes. 

■ /hsphere/local/conf  ig/ j ail/scripts/ j ailumount  is  a cron  task 
responsible  for  unmounting  unused  mountpoints  initiated  during  previous  SSH 
connections  by  users  with  valid  jail  shell. 
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Preventing  Manipulation  with  Logs 
Directory  Permissions 

The  security  scheme  prevents  untrusted  users  from  manipulating  logs  directory  and 
prohibits  users  other  than  httpd  from  entering  user  directory.  The  example  of  the 
permissions  and  groups  associated  with  the  directories  in  the  security  scheme  is  as 
follows: 

d— rwx-t  3 root  january  4096  Dec  8 20:32  january 
where: 

■ d rwx — t - permissions  with  a sticky  bit  that  prevents  users  from  making  any 

changes  to  logs  directory 

■ root  - owner  of  the  directory  (should  not  coincide  with  the  user  name) 

■ january  - directory  name 

■ 4 096  - size  in  bytes 

■ Dec  8 20 : 32  - date  of  last  modification 

january  - user  home  directory  name  Use  logslock  utility  to  put/remove  immutable  flag 
from  the  ~userhome/iogs  directory: 

logslock  -h 

Usage: 

/hsphere/shared/bin/logslock  [ -p  directory  ] [ -u  directory  ] [-s]  [- 

a] 

p : set  sticky  bit  on  home  directory 
u : unset  sticky  bit  from  home  directory 

a : unset  sticky  bit  from  home  directories  of  Parallels  H-Sphere  users 
s : set  sticky  bit  on  home  directories  of  Parallels  H-Sphere  users 


Note:  The  above  mentioned  permission  settings  for  user  home  directory  may  cause 
user  access  denial  via  ssh  if  public  key  authentication  is  used.  To  avoid  the  problem, 
you  can  disable  strict  sshd  mode  by  editing  sshd_config  file  and  restarting  sshd 
daemon  (/etc/ ssh/ sshd  conf  ig  file  on  Linux). 
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Altering  Virtual  Host  Configuration 

Sometimes  you  might  want  to  alter  Parallels  H-Sphere  so  it  creates  some  additional 
entries  in  Virtual  Host  config  files  for  a particular  plan.  You  might  need  it  to  integrate 
java  hosting,  or  some  3rd  party  CGI.  For  this,  you  would  have  to  edit  the  file 

common/ domain/vhost . config 

vhost . config  is  the  file  for  virtual  host  configuration.  It  has  a form  of  a template,  like 
any  other  template  used  in  Parallels  H-Sphere.  You  should  read  the  guide  on  template 
customization  in  Parallels  H-Sphere  Customization  Guide  and  create  custom  templates 
directory  as  well  as  make  a copy  of  the  file  before  you  start  modifing  the  file. 

First  of  all,  choose  a paramter  to  separate  one  plan  from  another.  To  do  that,  go  to 
Plans->Manage,  and  click  settings  next  to  the  plan.  Set  variable,  like  tomcat_support 
l.  After  that,  open  the  vhost.  config  template,  and  add: 

<if  account. plan. values. TOMCAT^SUPPORT  ==  "1"> 

</ if  > 

Within  this  IF  clause,  do  whatever  you  got  to  do  for  that  virtual  host  config.  This  way, 
only  plans  with  that  setting  would  have  this  entry. 

There  are  3 scripts  that  are  used  for  domain,  on  domain  creation,  deletion,  and  when 
some  alteration  to  the  config  is  done.  This  is  how  they  are  called: 

■ On  domain  creation: 

apache-vhost 
apache- save conf 

■ On  domain  removal: 

apache -del conf 


■ On  update: 

apache- save conf 


Script 

Description 

Parameters 

/hsphere/ shared/ sc 
r ipts/ apache - 
saveconf 

creates  a site 
configuration  file 

$1  - id  of  the  site 

/hsphere/ shared/ sc 
r ipts /apache - 
delconf 

deleting  vhost  file 

$1  - id  of  site  configuration 
removed  (we  don't  remove  files) 
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/hsphere/ shared/ sc 
r ipts/ apache -vhost 


creating  vhost 
directory 


$1  - directory  inside  user 

directory 

$2  - username 

$3  - group  name 

$4  - permission  to  the  directory 

$5  - domain 

$6  - instant  alias 

$7  - cpanel  login 

$8  - control  panel  url 

$9  - Parallels  SiteStudio  url 

$10  - Parallels  SiteStudio  class 

name  (you  should  not  care 

about  those,  it  is  done  for  the 

first  page  the  user  will  see) 


Calculating  Web  Traffic 


Important:  Parallels  H-Sphere  2.5  Beta  1 and  up  introduces  a completely  different 
approach  for  traffic  calculation  and  log  rotation.  Now  it  takes  into  account  both  incoming 
and  outgoing  traffic.  Therefore,  after  you  upgrade  from  Parallels  H-Sphere  version 
earlier  than  2.5,  your  clients  may  find  their  traffic  relatively  increased. 


There  are  two  types  of  traffic  calculation  in  Parallels  H-Sphere: 

■ Traffic  calculation  by  third-party  log  analyzers  - Parallels  H-Sphere  writes  log  files 
for  each  customer's  domain  into  respective  directories  to  make  them  available  for 
third-party  log  analyzers  included  into  default  installation:  Webalizer,  Modlogan,  and 
AWStats. 

■ Parallels  H-Sphere  built-in  traffic  calculation  - Parallels  H-Sphere  provides  its  own 
mechanism  of  traffic  calculation  used  in  billing.  Parallels  H-Sphere  traffic  reports  are 
available  in  admin  CP  as  Transfer  Traffic  Report  in  the  Reports  menu. 


In  this  section: 


Using  Third-Party  Log  Analyzers  for  Traffic  Calculation 134 

Calculating  Parallels  H-Sphere  Built-In  Traffic 135 
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Using  Third-Party  Log  Analyzers  for  Traffic  Calculation 

HTTP  Logs  for  each  domain  are  located  in  the 

/hsphere/local/home/ {user } /logs /<domain.name>/  directory,  in  the  following 
files,  provided  respective  resources  are  enabled: 

■ Transfer  log:  the  <domain.name>  file; 

■ Agent  log:  agent_log 

■ Referrer  log:  referrer  log 

■ Error  log:  error  log 

Here,  <user>  is  account  name,  and  <domain.name>  is  user  domain  name. 

Log  Rotation 

Parallels  H-Sphere  runs  daily  cron  script 

/hsphere/ shared/ scripts/ cron/ cron  rotate.pl: 

0 2 * * * nice  -15  /hsphere/shared/scripts/cron/cron_rotate . pi 

Log  rotation  data  is  taken  from  the 

/hsphere/local/ conf  ig/httpd/logrotate_conf  s/  directory.  The  files  there 
look  like: 

■ Transfer  log:  <domain.name> . transf  eriog . conf 

■ Agent  log:  <domain.name> . agentlog . conf 

■ Referrer  log:  <domain.name> . ref  erreriog . conf 

Error  log:  <domain.name> . errorlog . conf  The  cron  rotate . pi  script: 

1 Rotates  current  log  files  in  the  /hsphere/local/home/{user}/logs/{domain.name}/ 
directory  into  the  {domain. name}. 1 , {domain. name}. 2. gz,  {domain. name}.3.gz  etc. 
files  (the  first  one  NOT  being  gziped).  For  example: 


-rw 1 user29  user29  0 Jan  9 20:24  domain2 9 . test 

-rw 1 user29  user29  392000  Jan  9 20:24  domain2 9 . test . 1 

-rw 1 user29  user29  1495  Jan  9 20:24  domain2 9 . test . 2 . gz 

-rw 1 user29  user29  1496  Jan  9 20:11  domain2 9 . test . 3 . gz 


1 Runs  Webalizer's,  Modlogan's  and  AWStat's  command-line  utilities 
that  parse  current  logs  and  store  them  into  respective  directories  for 
each  domain  in  format  readable  for  these  analyzers. 

2 Webalizer,  ModLogAn  and  AWStats  take  statistics  from  the  access  log 
files  already  rotated.  Currently  used  access  log  files  for 
Webalizer/Modlogan/AWStats  are  specified  in  the  respective 
<LOG>.<domain.name>. txt  files: 

■ Webalizer:  webalizer  ,<domain.name> . txt 

■ Modlogan:  modlogan . <domain.name> . txt 

■ AWStats:  awstats  . <domain.name> . txt 
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cron_rotate  . pi  uses  the  /hsphere/ shared/ scripts /get logs  . pi  script  to 
update  the  latest  log  file  name  specified  in  these  files.  Also,  it  calls  Webalizer's, 
Modlogan's  and  AWStat's  command-line  utilities  that  parse  current  logs  and  store 
them  into  respective  directories  for  each  domain  in  format  readable  for  these 
analyzers: 

■ Webalizer:  /hsphere /local /home /<user>/<domain.name>/ webalizer/ 

■ Modlogan:  /hsphere /local /home /<user>/<domain.name>/modlogan/ 

• AWStats:  /hsphere/local/home/<user>/ <domain.name>/ aw  stats/ data/ 

Calculating  Parallels  H-Sphere  Built-In  Traffic 

Traffic  Log 

Parallels  H-Sphere  uses  the  mod_psoft_traf  fic  module  to  write  a more  informative 
and  convenient  traffic  log  into  the 

/hsphere/local/var/httpd/logs/traffic_log  file.  Traffic  log  has  the 

following  format: 

<unix_timestamp>  <domain_name>  <incoming_traffic>  <outgoing_traffic> 

For  example: 

1102091887  domain.com  623  623 
1102091888  domain.com  65  132 

Analyzing  Logs 

Parallels  H-Sphere  runs  daily  the  /hsphere/ shared/ scripts/ cron/ analyze  . pi 

cron  (on  page  33)  script: 

0 0 * * * nice  -15  /hsphere/shared/scripts/cron/analyze . pi 
/hsphere/ local /var/httpd/ logs /traf fic_log 

The  script  parses  traffic_iog  and  writes  specially  formatted  dd.mm.YYYY.txt  http 
log  files  in  the  /hsphere/iocai/var/ statistic  directory  (dd.mm.  yyyy  is  date 
timestamp). 

Log  format: 

| <domain.name>  | incoming  traffic  | outgoing  traffic  | 

TrafficLoader 

TrafficLoader  Parallels  H-Sphere  Java  class  is  in  charge  of  parsing  server  traffic.  It  is 
launched  daily  by  cron  (on  page  33): 

30  5 * * * su  -1  cpanel  -c  'java  psoft . hsphere . Traf ficLoader ' 

TrafficLoader  processes  Web,  mail,  FTP  and  virtual  FTP  traffic  in  the  formatted 
statistics  files  located  in  the  /hsphere/iocai/var/statistic  directory  and  inserts 
these  lines  into  the  translog  table  of  the  Parallels  H-Sphere  system  database. 
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T rafficLoader  also  calls  the  /hsphere/ shared/ scripts/xf  er_cat . pi  script  to 
rotate  the  already  loaded  statistics  files  to  the 

/hsphere/local/var/ statistic/ loaded  directory  as  dd .mm.  YYYY . txt . gz 

archives. 


Adding  Directories  for  User  Homes 

In  the  default  Parallels  H-Sphere  configuration,  user  homes  are  located  in 
/hsphere/local/home.  In  some  situations,  you  may  want  to  add  more  directories  for  user 
homes,  for  instance: 

■ You  need  to  add  a new  hard  drive.  In  this  case  you  must  mount  the  new  HDD 
partition  next  to  the  existing  home  directory: 

/hsphere /local /home 2/ 

■ You  have  web  and  Unix  RealServer  running  on  the  same  box,  but  would  like  to 
keep  their  user  homes  in  different  directories.  In  this  case  you  must  create  a 
directory  for  RealServer  user  homes: 

/hsphere /local/ real home/ 

You  can't  add  directories  for  user  homes  outside  /hsphere/iocal/  subtree, 
because  this  is  where  apache  suexec  is  configured  to  run  users'  cgi  scripts. 


> To  add  a directory  for  user  homes: 

1 In  your  admin  cp,  select  L.Servers  in  the  E. MANAGER  ->  Servers  menu. 

2 Select  the  server  you've  added  the  directory  for,  and  at  the  bottom  of 
the  page  that  appears  enter  the  name  of  the  new  directory. 

As  a result  of  this  procedure,  old  user  homes  will  remain  functional  in  their  old  location, 
and  new  user  homes  will  be  created  in  the  new  directory  regardless  of  the  plan. 


Installing  Ruby  on  Rails 

Parallels  H-Sphere  includes  support  for  Ruby  on  Rails 

(http://www.rubvonrails.org/down)  via  FastCGI.  However,  before  enabling  it  in  hosting 
plans,  administrators  need  to  manually  install  Ruby  on  Rails  on  their  Unix  Web  servers. 

> To  install  Ruby  on  Rails: 

1 Log  into  CP  server  as  cpanel . 

2 ssh  to  a Web  server  where  you  will  install  Ruby  on  Rails. 

3 Install  the  Ruby  package  from  its  home  page: 

1 . Download  the  latest  ruby  package  with  wget  for  Linux  or  fetch  for  FreeBSD  (in 
this  document  we  use  version  1 ,8-5p2  as  an  example,  but  the  version  could  be 
updated): 

wget  http : //ftp . ruby-lang . org/pub/ruby/1 . 8/ruby-l .8.5- 
p2 . tar . gz 
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2.  Untar  the  package: 

tar  zxvf  ruby-1 . 8 . 5-p2 . tar . gz 
cd  ruby-1 . 8 . 5-p2 

3.  Compile  and  install  the  package: 

. /configure 
make 

make  install 

4 Install  Ruby  Gems: 

1 . Download  the  latest  Ruby  Gems  version  with  wget  for  Linux  or  fetch  for 
FreeBSD  (in  this  document  we  use  version  0.9.4  as  an  example,  but  this  version 
could  be  updated): 

wget  http : //rubyforge . org/ f rs /download. php/ 17 190/ rubygems - 
0.9.4. tgz 

2.  Untar  the  package: 

tar  xzvf  rubygems - 0 . 9 . 4 . tgz 
cd  rubygems -0.9.4 
ruby  setup. rb 

5 Complete  Ruby  on  Rails  installation: 

gem  install  rails  --include-dependencies 

gem  install  -y  fcgi  --  --build-flags  --with-fcgi- 

dir=/hsphere/ shared/ 


After  that,  switch  the  Ruby  on  Rails  resource  on  under  Web  Services  in  a Unix  hosting 
plan  to  enable  RoR  for  users. 


Installing  ChililSoft  ASP 

This  guide  describes  the  installation  of  ChililSoft  ASP  to  Parallels  H-Sphere  web  box. 

It  is  advisable  to  read  the  README  file  that  contains  Chili IASP  bundle  to  get  familiar 
with  Chili  IASP  general  issues  and  features. 

WORKFLOW 

1 Download  ChililSoft  ASP  tarball. 

2 Run  the  command 

# mkdir  casp 

3 Run  the  command 

# tar  xf  chiliasp-3 . 6 . 2L . 1047a . tar  -C  casp 

4 Run  the  command 

# cd  casp  &&  ./install 
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5 You  will  see  dialogue  windows  in  the  order  set  below.  We  shall  lead 
you  though  the  procedure  and  give  you  the  responces  required  for  the 
correct  Sun  Chili ISoft  ASP  installation. 

On  each  step,  you  will  have  to  choose  one  of  the  options  suggested. 
The  default  choice  is  shown  in  square  brackets  e.g.  [1],  the  option  that 
you  need  to  choose  is  shown  in  bold  in  the  description  below  next  to 
the  default  one,  e.g.  [1]  2 - the  correct  choice  is  option  2. 

Step  I. 


Sun  Chili !Soft  ASP  - Installation 


Setup  will  now  install  the  files  needed  to  run  and  configure  Sun  Chili  ISoft  ASP  to  a 
directory  that  you  specify.  To  accept  the  default  (shown  in  brackets  below),  press 
Enter.  To  specify  a different  directory,  enter  the  pathname  and  then  press  Enter. 
Note:  Configuration  options  specific  to  this  installation  are  contained  in  the  directory 
that  you  specify.  Make  a note  of  this  location,  so  you  can  easily  find  Sun  Chili  ISoft 
ASP  files  at  a later  time. 


Enter  the  directory  in  which  to  install  Sun  Chili  ISoft  ASP  [/opt/casp] 

/hsphere/shared/casp 

Extracting  files  to  /hsphere/shared/casp  ... 

+ bean-classes  package  . done. 

+ bean-jre  package done. 

+ bean  package  . done. 

+ caspdoc  package done. 

+ caspsamp  package  ...  done. 

+ casp  package  . done. 

+ chilicom  package  ...  done. 

+ components  package  . done. 

+ installer  package  . done. 

+ license  package  . done. 

+ module  package  . done. 

+ odbc-direct-40  package done. 

+ odbc-opensource  package  . done. 

+ server  package  ..  done. 

+ sqlnk-4_51  package  . done. 

+ chili-tools-linux2  package  ..  done. 

+ supporting  binary  / library  packages  . done. 

Step  II. 


Sun  Chili  ISoft  ASP  - Product  Serial  Number 


Sun  Chili  ISoft  ASP  requires  a valid  serial  number  to  run.  If  you  downloaded  this 
product  from  the  Web,  you  should  have  received  an  e-mail  message  that  included 
your  serial  number.  If  you  are  installing  this  product  from  a CD-ROM,  the  serial 
number  is  printed  on  the  CD-ROM  case.  If  you  do  not  have  a serial  number,  enter 
'n'  below  to  receive  a 30-day  trial  license. 
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Note:  iPlanet  6.0  users  are  already  licensed  to  use  this  product  and  do  not  need  to 
enter  a serial  number.  If  you  are  using  iPlanet  6.0,  enter  'n'  below  to  receive  a full, 
unlimited  license. 


Do  you  have  a Sun  Chili ISoft  ASP  Product  Serial  Number  (y/n)?  [y]  y 

Note:  If  you  wish  to  exit  out  of  the  license  key  installer,  type  none. 

Enter  your  Sun  Chili  ISoft  ASP  Product  Serial  Number 
[none]  Y_0_U_R_  S_E_R_I_A_L 

Step  III. 


Sun  Chili  ISoft  ASP  - Bundled  Apache  1.3.19  Configuration 


Sun  Chili  ISoft  ASP  includes  a ready-to-run  Apache  1 .3.1 9 Web  server  that  is 
configured  with  Microsoft  (TM)  FrontPage  2002  Server 

Extensions  support  and  EAPI  (Extended  API).  If  you  have  not  yet  configured  a Web 
server,  you  now  have  the  option  to  install  this  preconfigured  Apache  Web  server. 

Note:  Sun  ChiliSoft  ASP  supports  but  does  not  install  FrontPage  2002  Server 
Extensions;  those  must  be  obtained  from  Microsoft.  For  more  information  about  Sun 
ChililSoft  ASP  support  for  FrontPage  2002  Server  Extensions,  see  'Chapter  3'  in  our 
production  documentation.  For  more  information  about  EAPI,  including  the  mod_ssl 
/ OpenSSL  module,  visit  www.modssl.org 


Would  you  like  to  install  the  bundled  Apache  1 .3.19  Web  server  (y/n)?  [n]  n 

Step  IV. 


Sun  ChililSoft  ASP  - Language  Selection 


Sun  ChililSoft  ASP  supports  various  languages.  Select  the  language  you  want  to 
use  from  the  list  below. 

1 . English  - US 

2.  English  - British 

3.  Japanese  Shift-JIS 

4.  German 

5.  Dutch 

6.  Spanish 

7.  French 


Which  language  would  you  like  to  use?  [1]  1 
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Step  V. 


Sun  ChiliiSoft  ASP  - Configuring  Java  Support 


The  Sun  Chili IBeans  component  allows  you  to  directly  access  Java  objects  and 
classes  from  inside  your  ASP  scripts.  For  this  functionality  to  be  provided,  a Java 
runtime  environment  (JRE)  must  be  installed.  Sun  ChiliiSoft  ASP  includes  JRE 
1 .3.1 . While  other  JREs  are  supported,  the  use  of  JRE  1 .3.1  is  strongly 
recommended.  Choose  option  1 to  use  the  bundled  JRE. 

1 . Use  the  bundled  JRE  1 .3.1 . 

2.  Specify  the  path  to  an  existing  JRE. 

3.  Disable  Java  support. 


Which  JRE  would  you  like  to  use?  [1]  3 

Are  you  sure  you  want  to  disable  Java  support  (y/n)?  [n]  y 

Step  VI. 

Sun  ChiliiSoft  ASP  - Web  Server  Auto-Detection 


Setup  will  now  conduct  a search  of  your  system  to  generate  a list  of  installed  Web 
servers.  On  the  next  screen,  you  have  the  option  to  enable  ASP  support  for  one  of 
these  detected  Web  servers.  If  you  want  to  skip  this  step,  you  can  specify  the 
pathname  to  a specific  Web  server  by  choosing  option  4 below. 

1 . Exhaustive  search  (slow) 

2.  Search  in:  /usr,  /opt,  /etc,  /var  (moderate) 

3.  Search  the  common  Web  server  locations  (fast) 

4.  Don't  search  (specify  Web  server  on  next  screen) 


Which  type  of  search  would  you  like  to  perform?  [2]  4 

Step  VII. 


Sun  ChiliiSoft  ASP  - Web  Server  Configuration 


No  Web  servers  have  been  detected.  As  options,  you  can  manually  specify  Web 
server  information  to  aid  in  detection,  direct  Setup  to  try  to  detect  more  Web 
servers,  or  delay  Web  server  configuration  until  another  time. 

1 . Specify  the  Web  server. 

2.  Attempt  to  auto-detect  more  Web  servers. 

3.  Do  not  configure  a Web  server. 


Which  configuration  option  would  you  like  to  perform?  [1]  1 
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Step  VIII. 


Sun  Chili ISoft  ASP  - User-specifed  Web  Server  Configuration 


Listed  below  are  the  types  of  Web  servers  to  which  this  version  of  Sun  Chili  ISoft 
ASP  will  install: 

1 . Apache 

2.  Netscape  / iPlanet 

3.  Zeus 

4.  Cancel  user-specified  Web  server  configuration. 


Which  Web  server  type  do  you  want  to  configure?  [1]  1 

BEFORE  REPLYING  TO  THE  NEXT  QUESTION,  DO  THE  FOLLOWING  STEPS 
FROM  ANOTHER  SERVER  CONSOLE: 

a)  check  if  your  version  of  Parallels  H-Sphere  Apache  server  is  different  from  the 
suported  bundle  version 

# /hsphere/shared/apache/bin/httpd  -v 

b)  if  it  is,  do  two  additional  steps: 

#mkdir  -p 

/hsphere/shared/casp/module/linux2_optimized/apache_1 .3.{corresponding_numbe 
r}/eapi 

#cp 

/hsphere/shared/casp/module/linux2_optimized/apache_{number_of_bundle_vesion 
}/mod_casp2.so  \ 

/hsphere/shared/casp/module/linux2_optimized/apache_1 .3.{corresponding_numbe 
r}/eapi 

c)  return  to  the  installation  console. 

NOTE:  Regardless  of  this  fact,  you  may  be  able  to  build  your  own  module  that 
supports  this  version  of  Apache.  Refer  to  Sun  Chili  ISoft  ASP  documentation  for 
information  on  building  your  own  module.  After  the  module  has  been  built,  proceed 
to  the  following  steps: 

(1)  # mkdir  -p 

/hsphere/shared/casp/module/linux2  optimized/apache  1.3.23/eap 
i 

(2) #  cp  <generated  build  dir>/mod  casp2 . so 

/hsphere/shared/casp/module/linux2  optimized/apache  1.3.23/eap 
i 

(3)  Re-run  the  the  installer  by  executing  the  following  script: 

HASH (0x81b9b84) -{ asphome } / INSTALL/ install 

After  placing  the  file  into  the  created  module  directory,  the  installer  will  recognize  it 
as  a supported  Web  server  and  act  accordingly. 
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Step  IX. 


Sun  Chili ISoft  ASP  - Apache  Configuration 


Because  of  the  way  the  Apache  Web  server  works,  few  of  the  configuration 
questions  listed  below  can  be  answered  outright.  However,  wherever  possible, 
default  values  have  been  provided  for  some  of  the  questions. 

Note:  To  exit  Web  server  configuration,  type  'none'  for  the  listed  option. 


Enter  the  path  and  file  name  of  the  Apache  Web  server  configuration  file: 
[none]  /hsphere/shared/apache/conf/httpd.conf 

Enter  the  path  and  file  name  of  the  Apache  binary: 

[/hsphere/shared/apache/bin/httpd] 

Step  X. 


Sun  Chili  ISoft  ASP  - Web  Server  Configuration 


The  following  list  contains  all  currently  detected  Web  servers.  If  the  Web  server  for 
which  you  want  to  enable  ASP  support  appears  below,  enter  the  number  that 
corresponds  to  the  Web  server.  If  the  Web  server  is  not  listed,  you  can  manually 
specify  Web  server  information  to  aid  in  detection,  direct  Setup  to  try  to  detect  more 
Web  servers,  or  delay  Web  server  configuration  until  another  time. 

1 . Apache  Secure  Server 

Settings  file:  /hsphere/ shared/ apache/ conf /httpd.  conf 

Port:  80 

2.  Specify  the  Web  server. 

3.  Attempt  to  auto-detect  more  Web  servers. 

4.  Do  not  configure  a Web  server. 


Which  configuration  option  would  you  like  to  perform?  [1]  1 

Step  XI. 


Sun  Chili  ISoft  ASP  - Web  Server  Verification 


Setup  has  automatically  detected  the  following  information  about  the  Web  server 
you  selected  on  the  previous  screen.  If  the  information  is  correct,  type  'y'  and  press 
Enter.  If  the  information  is  incorrect  type  'n',  press  Enter,  and  then  select  'Specify 
the  Web  server'  from  the  menu. 

Web  server  information: 

Main  configuration  file:  /hsphere/ shared/ apache/ conf /httpd.  conf 
Binary:  /hsphere/ shared/ apache/bin/httpd 

Version:  1 .3.19 
Type:  Apache 
Port:  80 

Root:  /hsphere/shared/apache 
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The  Web  server  information  is  correct  (y/n).  [n]  y 

Step  XII. 


Sun  Chili !Soft  ASP  - Server  Configuration 


Setup  will  now  configure  the  Sun  Chili ISoft  ASP  Server.  Unless  you  are  an 
experienced  Sun  Chili  ISoft  ASP  user,  it  is  strongly  recommended  that  you  use  the 
default  configuration  settings  (option  1 , below).  If  you  choose  the  custom 
configuration  option,  you  will  be  asked  to  specify  a number  of  settings.  For  detailed 
information  about  configuring  Sun  ChililSoft  ASP,  see  'Chapter  3'  in  the  product 
documentation. 

1 . Default  configuration. 

2.  Customize  configuration. 

3.  Choose  another  Web  server  to  install  to. 


Select  a configuration  option.  [1]  1 

Step  XIII. 


ChililSoft  ASP  - Administration  Console  Installation 


Setup  will  now  install  the  Sun  ChililSoft  ASP  Adminstation  Console.  Unless  you  are 
an  experienced  Sun  ChililSoft  ASP  user,  it  is  strongly  recommened  that  you  choose 
the  default  configuration  (option  1,  below).  If  you  choose  the  custom  configuration 
option,  you  will  be  asked  to  specify  a number  of  settings.  For  detailed  information 
about  configuring  the  Sun  ChililSoft  ASP  Adminstration  Console,  see  'Chapter  3'  in 
the  product  documentation. 

Note:  If  you  choose  the  'Default  configuration'  option,  the  username  and  password 
will  be  set  to  default  values.  To  protect  the  security  of  your  server,  you  should 
change  these  settings  immediately  after  installation.  For  more  infromation,  see  the 
product  documentation. 

1 . Default  configuration 

2.  Custom  configuration 


Select  a configuration  option  for  the  Administration  Console.  [1]  1 
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Step  XIV. 


Sun  Chili  ’Soft  ASP  - Administration  Console  Information 


Setup  has  finished  installing  the  Administration  Console.  To  configure  Sun  Chili ISoft 
ASP,  you  can  connect  to  the  Administration 

Console  from  a URL  or  from  the  command  line,  as  shown  below.  For  more 
information  about  configuring  Sun  ChililSoft  ASP,  see  'Chapter  3'  in  the  product 
documentation.  It  is  a good  idea  to  print  this  page  for  future  reference. 


To  connect  from  a browser,  use  this  URL:  http:  //gargona .psoft : 5100 
To  start,  stop  and  add  users,  use  this  script:  /var/casp/admtool 
The  console's  username  is:  admin 
The  console's  password  is:  root 

To  continue,  press  Enter. 

Step  XV. 


Sun  ChililSoft  ASP  - Setup  Complete 


Sun  ChililSoft  ASP  has  been  successfully  installed!  Important  next  steps: 

--  Read  the  README  file  that  came  with  Sun  ChililSoft  ASP.  This  file  contains  the 
latest  installation  and  application  notes. 

- Read  the  'Getting  Started'  section  in  the  'Sun  ChililSoft  ASP  Quick  Start  Guide.' 
This  guide  provides  basic  information  about  getting  started  with  Sun  ChililSoft  ASP, 
and  points  you  to  additional  resources. 

- Take  a moment  to  register  this  product.  By  registering  you  will  be  eligible  for  30 
days  of  free  introductory  support.  Register  at:  http://www.chilisoft.com/reqister 


Summary  file:  /var/casp/logs/install  summary 

6 If  the  installation  was  performed  correctly,  corresponding  Chili ! AS P 
services  should  be  activated.  Use 

# ps  -ax  | grep  casp 

Also,  check  the  httpd.conf  file  for  the  presence  of  additional  directives.  Use 

# grep  casp  /hsphere/shared/apache/conf /httpd.conf 

7 If  all  is  OK,  copy  the  web  content  of  ASP  test  scripts  into 
corresponding  default  "DocumentRoot"  directory 

# cp  -Rp  /hsphere/shared/casp/caspsamp 
/hsphere/ shared/apache/htdocs/ 

8 Check  the  operation  of  ASP  test  scripts  via  the  URL 
http://vour  Webserver  name/caspsamp 

9 You  may  reinstall  Chili !ASP.  In  this  case,  you  need  to  execute  the 
/hsphere/shared/casp/unistal!  script  prior  to  the  re-installation. 

NOTE:  It  is  advisable  to  avoid  restarting  Apache  when  installing  ChililSoft  ASP  even  if 
suggested  so  by  the  installation  script. 
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Installing  mod_perl 

This  guide  describes  the  installation  of  mod_perl  to  Parallels  H-Sphere  box. 

As  Apache  server  is  installed  without  mod_perl  support  during  Parallels  H-Sphere 
installation,  the  simplest  way  to  include  this  extension  is  through  building  mod_perl  as  a 
DSO  outside  the  Apache  source  tree  via  the  new  Apache  1 .3  support  tool  apxs 
(APache  extension). 

To  install  mod_perl: 

1 Download  the  latest  mod_perl  source  and  documentation  from 
http://perl.apache.org.  Complete  documentation  may  be  found  at 
http://www.cpan.org/modules/bv-module/DB  File.  The  Apache- 
mod_perl_guide  installer  is  located  at  the  same  address. 

2 Fulfill  the  following  build  steps: 

% tar  xzvf  mod  perl-x . xx . tar . gz 
% cd  mod  perl-x. xx 
% perl  Makefile. PL  \ 

USE_APXS=1  \ 

WITH  APXS=/hsphere/shared/apache/bin/apxs  \ 

EVERYTH ING=1  \ 

[•  • •] 

% make  &&  make  install 


This  will  build  the  DSO  libperl.so  outside  the  Apache  source  tree  with  the  new 
Apache  1.3.x  support  tool  apxs  and  install  it  into  the  existing  Apache  hierarchy.  For 
example,  if  you  want  to  use  mod_perl  for  Web  server,  you  need  to  set 
WITH_APXS=/hsphere/shared/apache/bin/apxs.  Following  the  successful! 
installation  the  following  should  appear: 

a /hsphere/ shared/ apache /libexec/libperl . so  file 
b two  additional  directives  in  the 

/hsphere/local/config/httpd/httpd.  conf  file  (see  COnfig  file 
customization  from  Appendix  C of  Parallels  H-Sphere  Installation  Guide  for 
making  changes  into  httpd.  conf): 

LoadModule  perl  module  libexec/libperl . so 
AddModule  mod  perl.c 

3  To  make  sure  that  mod_perl  works  correctly,  you  may  test  it  by 
entering  in  the  httpd. conf  file  a test  line  similar  to  the  one  below: 
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Alias  /perl/  /path_to_directory/ 

PerlModule  Apache :: Registry 
<Location  /perl> 

SetHandler  perl-script 
PerlHandler  Apache :: Registry 
Options  ExecCGI 
allow  from  all 
PerlSendHeader  On 
</Location> 

and  create  the  specified  above  perl  script  without  mentioning  the  perl  interpreter: 

/hsphere/ shared/ SiteStudio/public  html/perl/test . pi 

Next,  check  if  it  works  correctly  by  trying  out  the  link: 

http://some  url/perl/test .pi 

NOTE:  If  you  plan  on  intensely  using  the  mod_perl  feature,  it  should  be  properly 
documented.  Download  and  install  the  documentation  at 
http://www.cpan.org/modules/bv-module/DB  File. 


Installing  Zend  Optimizer 

Zend  Optimizer  is  a free  application  that  runs  files  encoded  by  Zend  Encoder, 
enhancing  the  running  speed  of  PHP  applications.  This  free  application  uses  multi-pass 
code  optimizations  to  speed  up  PHP  applications.  The  increase  in  speed  reduces  CPU 
load  for  the  server  typically  cutting  latency  time  in  by  20-50%. 

1 To  start  the  installation,  you  have  to  download  Zend  Optimizer.  You 
can  do  that  from  the  site 

www.zend.com/store/free  download.php?pid=1 3.  You  should  have 
PHP  version  4.1 .0  or  higher. 

2 Login  to  your  web  box  where  Zend  Optimizer  has  to  be  installed. 

3 For  Zend  installation,  you  must  have  the  file  php.ini  in  the  directory: 

~ht tpd/ conf /php4 /php . ini  or  ~ht tpd/conf /php5 /php . ini . 
-httpd/conf /php . ini  links  to  the  file  corresponding  to  php  version 
being  active. 

Since  the  distribution  doesn't  include  this  file,  you  have  to  copy  php.ini  to  the 
directory  specified  above,  or,  place  there  a symlink  to  the  php.ini  in  your  PHP 
installation  directory. 

4 Go  to  the  directory  where  your  Zend  distribution  is  downloaded  and 
extract  it  using  the  following  command: 

tar  xzf  Zend*****  .tar  .gz  - the  asterisks  stand  for  any  characters 

After  executing  this  command,  Zend  Optimizer  directory  will  be  created.  The  exact 
name  of  this  directory  depends  on  the  Zend  version  and  system  characters. 

5 To  proceed  with  the  installation,  enter  the  following  commands: 

cd  Zendoptimizer***  (the  asterisks  stand  for  any  characters)  - move  to  the 
directory  where  your  Zend  lies 
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. /install . sh  - start  Zend  installation 

6 Read  the  license  carefully.  If  you  agree,  enter  Yes,  otherwise  enter 
No.  You  will  be  asked  to  choose  the  directory  where  you  want  to 
install  Zend  (/usr/lib/zend  by  default).  The  installer  will  also  ask 
you  of  the  Apache  bin  directory  (it  is  by  default 

/hsphere/  shared/  apache  / bin)  and  of  the  location  of  php  .ini 
(~httpd/conf /php4 /php . ini  or  ~ht tpd/ conf /php5 /php . ini) 

Follow  the  further  instructions. 

7 Finally,  the  installer  would  suggest  to  restart  Apache.  You  must  do  it 
either  directly  from  the  installer  or  manually  (on  page  55)  after  the 
installation. 

8 If  apache  crashes  with  a segmentation  fault  error,  the  most  probable 
reason  is  that  the  file  usr/iocai/lib/php . ini  was  created 
incorrectly.  Open  it  with  a text  editor  and  remove  all  lines  except  the 
first  five  so  php. ini  file  looks  as  follows: 

zend  gui  password=your  encoded  zend  gui_password 
[PHP] 

zend  extension=/ usr/ local /Zend/ lib/ ZendOptimizer . so 
zend  optimizer . optimization  level=15 

9 Check  if  Zend  was  succefully  installed  by  putting  a php  file  with  the 
following  content  to  any  directory  of  your  site: 

<?  phpinfo();  ?> 

Then  open  this  file  in  a browser.  Zend  Optimizer  sections  must  appear.  If  your  Zend 
Optimizer  was  installed  successfully,  the  following  items  will  be  enabled: 


Optimization  Pass  1 

Enabled 

Optimization  Pass  2 

Enabled 

Optimization  Pass  3 

Enabled 

Zend  Loader 

Enabled 

10  If  one  of  the  given  items  was  not  enabled,  contact  Zend  Optimizer 
support. 
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Mail  System 

This  chapter  describes  tasks  you  may  need  to  do  on  your  Parallels  H-Sphere  mail 
server(s). 

In  this  chapter: 

Understanding  Parallels  H-Sphere  Mail 149 

Choosing  Remote  Web  and  MySQL  Logical  Servers  for  Horde  Webmail  Frontend155 

Changing  Mail  Server  Roles 1 56 

Blocking  IPs  on  Mail  Servers 1 57 

Adding  Qmail  Settings  to  IP/Subnet 158 

Bouncing  Mail 158 

Configuring  Qmail 160 

Choosing  Remote  MySQL  Logical  Server  for  SpamAssassin 180 

SPF  and  SRS 181 

Updating  SpamAssassin  Rulesets  Automatically 184 

Migrating  Mail  Server/IP 188 

Moving  Mail  Domains 191 

Calculating  Mail  T raffic 192 

SpamGuard  Setup 1 95 
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Understanding  Parallels  H-Sphere  Mail 

Parallels  H-Sphere  mail  system  consists  of  the  following  blocks: 

1 Parallels  H-Sphere  Mail  Package  (on  page  149):  includes  Qmail 
SMTP  server  with  a number  of  antispam/antivirus  and  other 
extensions,  vpopmail  POP3  server,  and  a number  of  other 
applications. 

2 Parallels  H-Sphere  Webmails  (on  page  150):  two  analogous  webmail 
applications,  SqWebMail  and  IMP  to  manage  mail  through  web 
interface.  System  administrators  can  choose  which  of  them  will  be 
offered  to  hosting  customers.  Apache  used  by  these  packages  is  the 
same  as  on  the  Parallels  H-Sphere  web  servers. 

3 Parallels  H-Sphere  IMAP  Server  (on  page  153):  Courier-IMAP  server 
package.  It  is  included  into  Parallels  H-Sphere  mail  system  by  default. 

4 Daemontools  (http://cr.yp.to/daemontools.html):  a collection  of  tools 
for  managing  UNIX  services  (such  as  ClamAV)  adapted  for  Parallels 
H-Sphere. 

All  mail  system  components  are  installed  with  Parallels  H-Sphere  by  default. 

In  this  section: 


Mail  Package 149 

Webmails 150 

IMAP  Server 153 


Mail  Package 

Parallels  H-Sphere  mail  service  is  represented  by  mail  package  called  hsphere-mail- 
service-4-<vers/on>. 


Included  Software 


Parallels  H-Sphere  mail  service  includes  popular  mail  applications: 

■ hsphere-qmail  (http://www.qmail.org/top.html)  - message  transfer  utility  on  the 
modified  sendmail  protocol.  (See  Qmail  configuration  (on  page  160)  manual) 

■ hsphere-vpopmail  (http://www.inter7.com/vpopmail.html)  - virtual  mail  utility  on  the 
POP  protocol. 

■ hsphere-ucspi  (http://cr.yp.to/ucspi-tcp.html)  - tcp  server  and  related  utilities. 

■ hsphere-autorespond  - autoresponder. 

■ hsphere-ezmlm  (http://www.ezmlm.org/)  - mailing  list  manager. 

■ clamav  (http://clamdmail.sourceforqe.net/)  - qmail  antivirus  module. 
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■ spamassassin  (http://www.spamassassin.org/index.html)  with  additional  perl 
modules  - qmail  antispam  module. 

Also,  ClamAV  and  SpamAssassin  require  MySQL  to  store  antivirus/antispam  data,  and 
they  run  under  the  supervise  utility  of  DJB  daemontools. 


Webmails 

Parallels  H-Sphere  comes  with  such  webmail  clients  as: 

■ IMP  that  includes  horde  (http://www.horde.org/)  and  its  plugins: 

■ imp  (http://www.horde.org/imp/) 

■ kronolith  (http://www.horde.org/kronolith/) 

■ mnemo  (http://www.horde.org/mnemo/) 

■ nag  (http://www.horde.org/nag/) 

■ turba  (http://www.horde.org/turba/) 

■ SqWebMail  (http://www.inter7.com/sgwebmail/sgwebmail.html) 

■ ImapProxy  (on  page  153) 

The  default  client  is  IMP,  and  you  don't  need  to  do  anything  to  use  it.  To  enable 
SqWebMail  over  IMP,  see  Enabling  SqWebMail  below. 

Horde  IMP  webmail  client  is  installed  on  each  mail  server.  In  earlier  versions,  it  was 
installed  on  one  of  the  Parallels  H-Sphere  web  servers. 

In  this  section: 


Enabling  SqWebMail 150 

Setting  SMTP  Server  for  IMP 151 

Enabling/Disabling  ImapProxy 151 

Localizing  Webmails 152 

ImapProxy 153 


Enabling  SqWebMail 

> To  set  SqWebmail  instead  of  IMP: 

1 Log  into  the  CP  server  as  the  cpanel  user  (on  page  65). 

2 Open  the  hsphere  . properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 

3 Comment  out  the  following  line: 

WEBJMAIL  = IMP 

4 Restart  Parallels  H-Sphere  (on  page  54). 
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Setting  SMTP  Server  for  IMP 

IMP  configuration  is  written  in  the  ~httpd/htdocs/horde/ config/ conf  .php  file. 

IMP  is  configured  in  such  a way  that  it  uses  local  sendmail  as  SMTP  server  by  default. 

IMP  is  automatically  switched  to  use  external  SMTP  server  when  smdcheck  qmail 
parameter  (on  page  160)  is  enabled.  When  you  make  an  update  to  a version,  reenable 
the  parameter.  If  you  want  to  make  an  update  with  disabled  smdcheck  parameter, 
execute  the  following  script: 

/hsphere/shared/scripts/mailsend  type.sh  smtp 

Usage: 

mailsend_type . sh  [ smtp  | sendmail  ] 

> To  configure  IMP  to  use  external  SMTP  server,  modify  conf . php  in  the  following 
way: 

1 Change  the  mailer  type  to  smtp.  For  this,  change  the  line: 


$conf [ ' mailer ' 

] [ ' type ' ] = 

' sendmail ' ; 

to: 

$conf [ ' mailer ' 

] [ ' type ' ] = 

' smtp ' ; 

Uncomment  the  following  line  and  specify  the  smtp  server: 

$conf [ ' mailer ' 
' smtp . example . 

] [ ' params ' ] 

. com ' ) ; 

= array ('host'  => 

where  smtp . example . com  should  be  a valid  smtp  server  name. 


Enabling/Disabling  ImapProxy 

ImapProxy  1 .2.4,  which  is  included  in  Webmail  package,  is  disabled  by  default. 
To  enable  it,  run  the  script: 

/hsphere/ shared/ scripts/ imapproxy-init  set 

To  disable  ImapProxy  1 .2.4,  run: 

/hsphere/ shared/ scripts/ imapproxy-init  drop 
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Localizing  Webmails 

The  /hsphere/local/ conf  ig/mail/ scripts/ add_locales  script  that  fixes  the 
Horde  localization  problem  on  TRUSTIX  OSs  is  included  into  the  package. 

Usage: 

add_locales  [ localel  locale2  . . . localeN  ] [ usage  ] [ list  ] 

Where: 

no  options  - adds  all  supported  by  HORDE  locales 
localel  ...  localeN  - adds  listed  locales 
list  - lists  all  supported  by  Horde  locales 
usage  - prints  this  message 

This  script  is  called  out  from  the  post-install  script  and  during  the  hsphere-webmails 
installation  adds  utf8  locales  only  for  Russian,  Italian,  French,  German,  Dutch,  Spanish, 
Portugese. 

To  add  the  languages  supported  by  Horde  but  not  installed  with  package  by  default,  run 
the  script  with  necessary  language  codes  (the  codes  should  be  delimited  by  a space). 
For  instance,  to  add  Hungarian  and  Chinese,  run: 

/hsphere/local/config/mail/scripts/add_locales  hu_HU  zh_CN 

You  can  view  all  possible  language  codes  by  running: 

/hsphere/local/conf ig/mail/ scripts /add_locales  list 


Note:  you  need  to  have  the  package  glibc-iocaies  installed  on  the  server  for  the 
proper  work  of  the  script! 
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ImapProxy 

ImapProxy  component  is  by  default  included  into  Parallels  H-Sphere  Webmail  package. 

ImapProxy  is  a daemon  that  proxies  IMAP  transactions  between  an  IMAP  client  and  an 
IMAP  server.  The  general  idea  is  that  the  client  should  never  know  that  it's  not  talking 
to  the  real  IMAP  server.  The  only  thing  that  makes  this  a slightly  unique  Imap  Proxy 
server  is  that  it  caches  server  connections. 

The  ImapProxy  daemon  is  /hsphere/shared/bin/in.  imapproxyd. 

The  startup  script  for  ImapProxy  daemon  is  /etc/init . d/imapproxy  for  Linux  and 

/ usr/ local/ etc/ rc  . d/ imapproxy . sh  for  FreeBSD. 

Usage  of  ImapProxy  daemon: 

Linux: 

/etc/init . d/imapproxy  [ start  | stop  | restart  | stat  | help  ] 

FreeBSD: 

/usr/local/etc/rc . d/imapproxy . sh  [ start  | stop  | restart  | stat  | help 
] 

where: 

■ start  starts  in. imapproxyd  service 

■ stop  stops  in. imapproxyd  service 

■ restart  stops  and  restarts  the  in. imapproxyd  service 

■ stat  displays  status  of  in. imapproxyd  service 

■ help  displays  help  message 

This  startup  script  uses  daemontools  (http://cr.yp.to/daemontools.html). 

ImapProxy  daemon  listens  to  144  port,  and  turns  to  143,  which  is  a default  courier-imap 
port.  Imp  is  configured  to  turn  to  144  port,  so  imp  connects  to  courier-imap  through  144 
port  (through  ImapProxy  daemon). 

Package  includes  statistic  tool  for  ImapProxy:  /hsphere/shared/bin/pimpstat. 

Usage  Of  /hsphere/shared/bin/pimpstat: 

/hsphere/shared/bin/pimpstat  -f  imapproxy . conf 

where  imapproxy.conf  is  the  configuration  file  for  ImapProxy  located  at 

/hsphere/local/ conf  ig/mail/ imapproxy  directory. 

IMAP  Server 

Parallels  H-Sphere  IMAP  Server  is  represented  with  two  components: 

■ courier-imap  (http://www.courier-mta.org/imap/) 

■ courier-authlib  (http://www.courier-mta.org/authlib/) 
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Courier-IMAP  is  a standalone  IMAP  server  that  can  be  used  with  Parallels  H-Sphere 
Qmail  server  to  provide  IMAP  access  to  Maildirs. 

Courier-IMAP  is  included  into  Parallels  H-Sphere  mail  system  by  default. 

IMAP  server  comes  with  IMAP  Before  SMTP  Authentication  support. 


In  this  section: 


Starting  IMAP  Server 154 

Configuring  IMP  with  IMAP 154 


Starting  IMAP  Server 

Courier-IMAP  server  is  started  automatically  with  Parallels  H-Sphere  by  running  the 
following  commands: 

Linux: 

/sbin/chkconf ig  --level  2345  courier- imapd  on 
/ etc/rc . d/init . d/ courier- imapd  start 
/ etc/rc . d/init . d/ courier-imapd-ssl  start 

FreeBSD: 

/usr/local/etc/rc . d/courier-imapd . sh  start 
/usr/local/etc/rc . d/courier-imapd-ssl . sh  start 


Note:  In  order  for  IMAP  SSL  to  start,  SSL  certificate  must  be  uploaded  through  the 
Control  Panel. 


Configuring  IMP  with  IMAP 

> To  configure  IMP  to  work  with  IMAP: 

1 Log  into  the  CP  server  as  the  cpanel  user  (on  page  65). 

2 Open  the  hsphere  . properties  file: 

vi  ~cpanel/ shiva/psof t_config/hsphere .properties 

3 Add  the  following  line: 

MAIL_PROTOCOL=imap 

4 Restart  Parallels  H-Sphere  (on  page  54). 
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Choosing  Remote  Web  and  MySQL 
Logical  Servers  for  Horde  Webmail 
Frontend 


Parallels  H-Sphere  mail  logical  server  is  by  default  installed  on  a physical  box  together 
with  Web  and  MySQL  servers  on  the  same  box,  thus  Webmail  frontend  uses  Apache 
and  MySQL  on  the  same  server. 

It  is  made  possible  to  choose  an  alternative  remote  Web  and  MySQL  servers  for  Horde 
Webmail  frontend.  This  is  in  particular  important  for  the  implementation  of  load 
balanced  mail  cluster  (on  page  406)  where  it  is  required  that  Webmail  is  configured  to 
use  remote  Web  and  MySQL  servers.  Also,  now  you  can  configure  one  Horde  Webmail 
frontend  to  manage  multiple  mail  servers. 

> To  choose  remote  Web  and  MySQL  servers  for  Webmail: 

1 Login  as  cpanel  user  (on  page  65)  and  set  the  following  property  in 

~cpanel / shiva/ psof t_conf ig/h sphere .properties : 

EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  54)  to  apply  changes. 

Important:  If  external_service_usage  is  not  set  or  is  not  true,  you  won't  be 
able  to  choose  external  Web  and  MySQL  servers  for  Webmail! 

2 In  admin  CP,  go  to  E. Manager  ->  Servers ->  L.Servers,  proceed  to  settings 
for  this  mail  logical  server,  and  Choose  Unix  Hosting  server  for  Horde 
under  Mail  Server  Additional  Options. 

3 Proceed  to  the  selected  Web  (Unix  Hosting)  logical  server  settings  in 
the  E. Manager ->  Servers ->  L.Servers  list  and  select  a remote  MySQL 
server  for  Horde  database  from  the  Choose  External  Horde  DB  Server 
dropdown  menu . 

4 Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
updater  with  the  hspackages  reconfig  option: 

hspackages  reconf ig=f rontend 

Note:  Regular  Parallels  H-Sphere  update  automatically  includes  the  reconfig 
option.  However,  for  best  performance  we  recommend  running  Parallels  H-Sphere 
updater  with  this  option  separately. 

More  about  Parallels  H-Sphere  updater  read  in  the  Update  Guide. 

5 To  move  Horde's  Web  and  DB  content  to  respective  remote  Web  and 
MySQL  logical  server  locations,  run  the  following  script  on  the  source 
box: 

/hsphere/pkg/ script s/uprocedures/ dbs_content  -h 


Usage: 
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dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 

dbtype:  horde  or  spamassassin  or  phpmyadmin 

ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the  corresponding 
mail  logical  server 

password:  this  option  is  required  only  in  the  case  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding  mail 
logical  server 


Changing  Mail  Server  Roles 

This  document  explains  how  to  have  incoming  mail  queued  on  a relay  mail  server  while 
the  master  mail  server  is  down  or  otherwise  unable  to  receive  mail. 

For  this,  you  need  to  do  two  things: 

1 Mark  the  backup  mail  server  as  relay. 

2 Allow  relaying  in  the  plan  so  that  users  can  use  the  relay  server. 

Every  active  mail  server  can  be  either  relay  or  master+relay. 

■ master+relay  means  that  (1 ) new  mail  domains  will  be  created  on  this  server  and 
(2)  the  server  will  receive  mail  for  domains  on  other  mail  servers. 

■ relay  (secondary  queue  server)  means  that  new  domains  won't  be  created  on  this 
server,  but  the  server  will  relay  mail  for  domains  on  other  servers. 

By  default,  all  mail  servers  are  set  as  master  and  relay,  which  is  the  recommended 
configuration. 


Note:  If  you  do  not  want  to  use  a server  with  new  domains  (neither  host  new  domains 
nor  relay  mail  for  them),  make  it  unavailable  for  signup. 

Important:  It  is  highly  recommended  to  move  static  mail  relays  from  a Web  server  to  a 
dedicated  mail  relay  server,  as  Web  content  on  the  same  server  with  mail  relay  may 
become  a target  for  spambot  attacks! 


> To  change  the  role  of  a mail  server  at  the  system  level: 

1 Log  into  the  control  panel  as  admin. 

2 Go  to  E.Manager->  Servers  ->  L.Servers  and  select  the  mail  server. 

At  the  bottom  of  the  form  that  appears,  choose  server  role  from  the  drop-down  box. 


Additional  options 

Mail  role  (master+relay,  relay) 

| master+relay  ! ▼ 

M 

relay 

Submit  | 
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You  can  allow  or  disallow  relaying  mail  for  a specific  plan.  With  relaying  allowed,  mail  to 
accounts  under  this  plan  will  be  queued  on  other  servers  when  their  mail  server  is 
down. 

1 Log  into  the  control  panel  as  admin. 

2 Select  Plans->Manage. 

3 Choose  the  plan. 

4 On  the  first  step  of  the  wizard,  check  Include  for  Mail  Relay. 


Mail  Services 

Email  Auto  Responder  9 

Include 

Mail  Box  Alias  0 

Include 

Mail  Forward  9 

Include 

Mailing  List  0 

Include 

Mail  Relay  9 

|T  Include  P Activated 

If  mail  relays  are  allowed  in  the  plan,  users  can  choose  a relay  server  for  a specific 
account  in  their  User  control  panel.  If  the  server  is  down,  mail  for  this  account  will  be 
queued  on  this  relay  server. 

1 Log  into  this  account. 

2 Go  to  Mail  Info  menu. 

3 Turn  Mail  Relay  on. 

This  will  add  an  MX  record  for  the  server  that  was  set  as  relay. 


Blocking  IPs  on  Mail  Servers 

To  fight  spam  or  block  unwanted  emails,  you  can  block  specific  IPs  from  sending  you 
mail.  The  incoming  messages  from  this  IP  will  bounce  back  to  the  sender. 

> To  deny  relay  to  specific  IP: 

1 Go  to  E. Manager  ->  Servers  - > Mail  Servers: 

2 At  the  bottom  of  the  page  choose  mail  server  from  the  drop-down  box. 

3 Enter  necessary  IP/subnet. 

4 Enter  note,  if  necessary,  and  click  the  Add  button. 

The  blocked  IP  will  appear  in  the  Mail  Server  Relays  section 

You  can  remove  the  blocked  IP  from  the  list  at  any  moment  by  clicking  the  Trash 
icon  on  the  right. 
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Adding  Qmail  Settings  to  IP/Subnet 

> To  add  mail  relay  and  other  Qmail  settings  to  a chosen  IP/subnet. 

1 Go  to  E. Manager  ->  Servers  - > Mail  Servers: 

2 Click  the  Add  button  and  fill  in  the  form: 

■ Choose  mail  server  from  the  drop-down  box 

■ Enter  necessary  IP/subnet  and  a comment,  if  necessary, 

■ Set  Qmail  parameters.  Some  of  them  are  checked  to  use  default  value.  To  enter 
custom  value,  uncheck  it. 

Note:  To  deny  mail  relay,  go  to  Blocking  IP  (on  page  157). 

3 Click  Submit.  The  record  will  appear  in  the  Mail  Relays  section 

You  can  remove  the  record  from  the  list  at  any  moment  by  clicking  the  Trash  icon  on  the 
right. 


Bouncing  Mail 

When  a mail  server  accepts  a message  and  later  decides  that  it  can't  deliver  the 
message,  it  is  required  to  send  back  a bounce  email  to  the  sender  of  the  original 
message.  These  bounce  emails  are  often  misdirected. 

This  document  outlines  the  correct  configuration  of  mail  server  where  mail  bouncing 
should  always  work.  Mail  servers  are  by  default  configured  in  accordance  with  this 
scheme. 

Mail  bouncing  policy  implies  the  following  three  independent  strategies: 

1 Separate  bounce  IP 

2 Processing  error  responses 

3 Bounced  mail  delivery 

See  Qmail  bounce  parameters  (on  page  160)  for  details. 


In  this  section: 


1 . Separate  IP  for  Sending  Bounced  Mail 1 59 

2.  Processing  Error  Responses 159 

3.  Bounced  Message  Delivery 160 
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1.  Separate  IP  for  Sending  Bounced  Mail 

Separate  IP  for  sending  bounced  mail  allows  sending  bounces,  but  isolates  them  to  a 
different  IP  address  (so  that  spamcop  can  block  them  without  blocking  other  mail). 

How  to  configure: 

The  respective  bounce  IP  network  alias  must  be  up.  Then,  specify  the  bounce  IP  in  the 

/var/ qmaii/ control /bound ngip  file  and  restart  qmail  or  set  the  bound ngip 

parameter  in  the  Qmail  Settings  form  in  the  administrator  CP. 

After  that,  restart  qmail. 


2.  Processing  Error  Responses 

There  are  2 main  error  status  groups: 

■ temporary  errors:  delivery  of  such  messages  is  done  during  queue  lifetime  period 

■ permanent  errors:  after  the  first  delivery  attempt  the  message  is  queued  as  a 
bounce  message 

In  many  cases  temporary  error  status  is  inadequate.  For  example,  the  absence  of 
mailbox  or  quota  overlimit  is  sometimes  considered  by  a remote  box  as  a temporary 
error  - as  a result,  the  message  may  remain  in  the  queue  during  lifetime  period. 

h sphere -mail -service  packages  adds  a possibility  to  configure  3 additional 
states: 

1 Consider  temporary  errors  as  permanent  errors  for  local  mail  delivery 

2 Consider  temporary  errors  as  permanent  errors  for  remote  mail  delivery 

3 Consider  temporary  errors  as  permanent  errors  for  local  and  remote  mail  delivery 

How  to  configure: 

Set  the  temperror  parameter  in  /var/qmail/ control/options: 

■ temperror=0  or  absent  (default)  - common  behavior; 

■ temperror=1  - consider  temporary  errors  as  permanent  errors  for  local  mail 
delivery; 

■ temperror=2  - consider  temporary  errors  as  permanent  errors  for  remote  mail 
delivery; 

■ temperror=3  - consider  temporary  errors  as  permanent  errors  for  local  and  remote 
mail  delivery. 
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3.  Bounced  Message  Delivery 

Bounced  message  delivery  is  performed  in  3 ways: 

1 Simple  bouncing:  message  is  bounced. 

2 Double  bouncing:  message  is  sent  to  a predefined  location. 

3 Triple  bouncing:  - message  is  discarded. 

Current  mail  configuration  allows  regarding  double  bounce  as  triple  bounce.  We  have 
added  a possibility  to  configure  common  bounce  delivery  as  double  bouncing  or  even 
triple  bouncing.  This  may  be  useful  when  queue  grows  big  and  common  message 
delivery  suffers.  However,  in  many  cases  this  configuration  is  not  recommended  and 
should  be  applied  only  in  critical  situations. 

How  to  configure: 

Set  the  strictbounce  parameter  in  /var/qmaii/ control/ options  if  necessary: 

■ strictbounce=1  - consider  simple  bounce  as  double  bounce 

■ strictbounce=2  - consider  simple  bounce  and  double  bounce  as  triple  bounce 


Configuring  Qmail 

Parallels  H-Sphere  offers  enhanced  Qmail  SMTP  server  configuration.  Most 
enhancements  have  been  added  to  fight  spam  at  the  server  level. 


In  this  section: 


Antivirus  and  Antispam  Filters  (SpamAssassin  and  ClamAV) 161 

Integrated  Antispam  Addons 163 

Qmail  Server  Settings 164 

Command  Line  Qmail  Configuration 1 75 

Syslog  Facility/Level  Configuration  For  rblsmtpd 176 

SMTP  Log 176 

Mail  Client  and  ESMTP  Destination  Server 177 

Qmail-spp  Support 178 

Qmail  TLS  Support 1 79 

Integrated  Plugins 179 
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Antivirus  and  Antispam  Filters  (SpamAssassin  and 
ClamAV) 

Qmail  incorporates  SpamAssassin  and  ClamAV  filters  at  the  server  level.  It  uses  an 
improved  qmail-queue  patch  concept,  where  the  use  of  the  QMAILQUEUE  variable  is 
replaced  with  checking  recipient  addresses  against  the  clamavciients  and 
spamdclients  databases  (see  the  drawing).  Parallels  H-Sphere  users  can  add  their 
mail  addresses  to  the  database  to  have  them  checked  for  spam  and  viruses.  User- 
defined  antispam  preferences  are  stored  in  a MySQL  database. 

Mail  is  filtered  by  standalone  clamd  and  spamd  services.  We  had  to  get  rid  of  the 
Qmail-Scanner  perl  wrapper,  because  it  is  rather  heavy  and  unreliable  for  high  load 
SMTP  servers.  Instead,  we  use  clamdmail  software,  http://clamdmail.sourceforqe.net/, 
which  is  fast  and  adapted  to  working  with  clamd  and/or  spamd. 


Incoming  Mail 
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In  this  section: 


Updating  Virus  Patterns 162 

Enabling  Antivirus  and  Antispam 162 

Configuring  ClamAV  and  SpamAssassin  at  the  Server  Level 162 

Restarting  ClamAV  and  SpamAssassin 162 

Updating  ClamAV  Database 163 

User  Settings 163 


Updating  Virus  Patterns 

Mail  server  cron  has  a script  that  updates  virus  patterns  every  day  at  12AM.  You  can 
manually  change  the  timing  of  the  cron. 

Enabling  Antivirus  and  Antispam 

ClamAV  and  Spamassasin  have  been  added  to  Parallels  H-Sphere  as  resources,  and 
can  be  enabled  and  disabled  from  the  control  panel: 

1 Global  Settings.  In  Plans  ->  Globals,  check  Antispam  and  Antivirus  and 
click  Submit  Query. 

2 Plans.  In  Plans  ->  Plans  select  the  plans  where  you  would  like  to  enable 
spam  and  virus  protection.  On  the  first  page  of  the  wizard,  enable 
Antispam  and  Antivirus.  Optionally,  set  prices  for  these  resources  on  the 
subsequent  steps. 


Configuring  ClamAV  and  SpamAssassin  at  the  Server  Level 

■ ClamAV:  edit  file  /hsphere/ local/ conf  ig/mail/ clamav/clamav . conf . 

The  format  and  options  of  this  file  are  fully  described  in  the  clamav.conf(5)  manual. 
Remember  - you  must  remove  the  "Example"  directive.  Be  careful  not  to  change  the 
values  of  LocalSocket  and  TCPSocket. 

■ SpamAssassin:  edit  file 

/hsphere /local/ conf ig/mail/ spamassas sin /local . cf  as  suggested  in 
Spamassassin  documentation 

(http://www.spamassassin.org/doc/Mail  SpamAssassin  Conf.html).  Note  that 
external  modules  like  Bayesian  rules,  razor2,  dec,  and  pyzor  are  not  included,  so 
please  be  careful  not  to  enable  related  options. 


Restarting  ClamAV  and  SpamAssassin 


See  Restarting  Services  (on  page  52). 
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Updating  ClamAV  Database 

Each  hour  cron  updates  ClamAV  antivirus  databases.  Execute  crontab  -l  to  see  the 
list  of  cron  tasks  for  a mail  server.  The  following  line  indicates  that  ClamAV  database  is 
updated  each  hour: 

0 * * * * /hsphere/shared/bin/freshclam  --quiet 

ClamAV  database  update  is  configured  in 

/hsphere/local/conf ig/mail/ clamav/ freshclam. conf. 

User  Settings 

ClamAV  and  Spamassasin  settings  can  be  configured  per  maildomain  and  individual 
mailbox.  Please  see  Parallels  H-Sphere  User  Guide  for  details. 

Integrated  Antispam  Addons 

Besides  SpamAssassin,  Parallels  H-Sphere  Qmail  includes  a series  of  third  party  and 
in-house  antispam  addons: 

■ Fehcom  Spamcontrol  patch,  http://www.fehcom.de/qmail/spamcontrol.html,  (based 
on  the  spamcontrol-2.4.17  release)  provided  with  opportunity  to  switch  whitelist 
extensions  on  and  off  dynamically 

■ qmail-smtpd  badmailfrom-unknown  addon, 
http://www.lamer.de/maex/creative/software/qmail/103-bmfunk/ 

■ Qmail  patch,  http://www.qmail.org/biq-concurrencv.patch,  to  allow  Qmail  to  use  a 
concurrency  greater  than  240 

■ doublebounce-trim  patch,  http://www.qmail.org/doublebounce-trim.patch,  to  discard 
doublebounces  without  queuing  them 

■ Jose  Luis  Painceira's  patch  that  deletes  the  body  of  bouncing  messages 
(http://qmail.org/qmail-send.mimeheaders.tar.qz).  This  patch  is  based  on  Fred 
Lindberg's  patch  that  preserves  the  MIME-ness  of  bouncing  MIME  messages 
(http://www.ezmlm.org/pub/patches/qmail-mime.tqz) 

■ qmail-maildir-i-i-.patch  (from  Vpopmail  distribution) 

■ Parallels  addon  that  checks  if  the  sender's  address  in  POP-before-SMTP 
authentication  is  local  and  the  recipient's  address  is  remote; 

■ Parallels  addon  that  checks  if  domain  name  in  the  sender's  address  matches  the 
domain  name  used  in  SMTP  authentication. 

■ Andre  Oppermann's  ext-todo  patch,  http://www.nrq4u.com/qmail/ext  todo- 
200301 05.patch,  which  solves  the  'silly  qmail  syndrome'.  That's  where  qmail  spends 
more  time  processing  incoming  email  than  scheduling  deliveries. 

■ big-DNS  patch,  http://www.ckdhr.com/ckd/qmail-103.patch,  which  fixes  oversize 
DNS  packet  problem. 

■ Modified  version  of  Qmail  chkuser  0.6  patch  (http://www.shupp.org/)  that  checks  if 
the  vpopmail  recipient  is  valid  before  accepting  the  message. 
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Qmail  Server  Settings 

Default  Qmail  server  settings,  including  antispam  options,  can  be  configured  in  the 
admin  control  panel  in  the  E. Manager/Servers/Mail  Servers  menu. 

> To  configure  Qmail  settings: 

1 Select  Mail  Servers  from  the  E.Manager  ->  Servers  menu: 


E.  Manager 

Servers 

Enterprise 

Background  Jobs 

P.  Servers 

3rd  Party  Tools 

Add  P.  Server 

Packages 

L.  Servers 

DNS  Manager 

Add  L.  Server 

Shared  SSL  Manager 

Server  Groups 

Start  Account  Move 

Mail  Servers 

Started  Move  Processes 

VPS  Network  Gateways 

Other 

MS  Exchange 

Shell  Request  Manager 

Installation  Wizard 

Allocated  Servers 

2 Click  the  Action  icon  in  the  Mail  Server  Settings  section: 


Mail  Servers  Settings 

Mail  server 

Action 

mail.  rh27-u24update.  test 

M || 
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3 Edit  qmail  settings  following  on-screen  explanations  and  click  Submit: 


Qmail  Server  Parameters 

Please  be  careful  while  changing  these  parameters 

tcpsessioncount  @ 

[40  + 

(*The  number  of  concurrent  SMTP 
connections) 

concurrencyremote 

a 

|1 00  + 

(*The  number  of  qmail-send  processes  of 
message  delivery  to  remote  addresses) 

concurrencylocal  Q 

|50  + 

(*The  number  of  qmail-send  processes  for 
message  delivery  to  local  addresses) 

databytes  Q 

1°  + 

(^Maximum  size  of  a message) 

IMPORTANT: 

Values  can  be  of  three  types: 

■ Text:  can  be  either  a line,  like  @1 2.34.56.78,  or  a list,  for  example  a list  of 
addresses  in  badmailfrom. 

badmailfrom  is  the  file  that  containts  a list  of  senders  mail  isn't  accepted  from. 

• Number,  like  1 000  in  databytes. 

databytes  is  the  file  that  contains  the  maximum  allowed  size  of  a message. 

• Boolean,  like  0 or  1 in  smtpauth. 

0 disables  SMTP  Auth,  1 enables  it. 

Note:  0 is  also  set  by  default  if  the  corresponding  control  file  is  absent. 


Thus,  for  example,  if  you  have  to  enable  SMTP  Auth,  you  create/modify  the 
/ var/ qmail/ control/ smtpauth  control  file  and  put  1 in  it.  To  disable  SMTP  Auth, 
put  0 in  the  control  file  or  just  delete  the  control  file. 

Also,  text  values  may  contain  patterns:  wildcard  expressions  to  set  the  range  of  emails, 
domains  and  IPs  for  filtering  rules. 

Control  characters  in  patterns: 

■ Exclamation  mark  (!):  allows  you  to  INCLUDE  particular  clients/addresses  by 
simply  putting  an  exclamation  mark  (!)  as  first  character  in  the  line. 

■ Asterisk  (*):  General  pattern  matching  character;  one  or  more  preceding. 

■ Question  Mark  (?):  Match  zero  or  one  preceding. 

■ Backslash  (\):  Literal  expression  of  following  character,  eg.  \[. 
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■ Match  one  from  a set  ([...]):  i.e.  [Ff][Aa][Kk][Ee]  matches  FAKE,  fake,  FaKe, 

FAKe  etc. 

Qmail  settings: 

■ tcpsessioncount:  the  number  of  concurrent  SMTP  connections.  Default:  40. 
After  setting  this  parameter,  Qmail  restart  (on  page  56)  is  required. 

■ concurrencyremote:  the  number  of  qmail-send  processes  of  message  delivery 
to  remote  addresses.  Default:  100.  Max:  500.  If  Max  is  exceeded,  Max  value  is  set. 

■ concurrency  local:  the  number  of  qmail-send  processes  for  message  delivery  to 
local  addresses.  Default:  50.  Max:  500.  If  Max  is  exceeded,  Max  value  is  set. 

■ databytes:  maximum  size  of  a message.  Default:  0 (unlimited). 

■ queuelifetime:  the  message  queue  lifetime  in  seconds.  Default:  604800  (1 
week). 

■ bouncef  rom:  the  email  user  messages  are  bounced  from. 

Default:  MAILER-DAEMON; 

■ maxrecipients:  maximum  number  of  recipients  in  the  "TO:",  "CC:",  and  "BCC" 
fields.  Defaults  (unlimited). 

■ maxwrongrcpt:  maximum  number  of  wrong  recipients  in  the  envelope.  Default:  0 
(unlimited). 

■ timeout smtpd:  TCP  connection  timeout  in  seconds.  Default:  1200. 

■ newline:  accept  or  reject  mail  from  mail  user  agents  (MUA)  that  send  commands 
without  CR  (carriage  return).  Default:  0 (disabled); 

■ strip  single  quotes:  enable  or  disable  stripping  single  quotes  (referred  to  in  the 
spamcontrol  manual  as  the  feature  that  may  cause  unpredictable  results).  Default:  0 
(disabled); 

■ lowercase:  enable  or  disable  conversion  of  mail  address  to  lowercase;  it  may  be 
useful  in  filtering  patterns,  for  case-sensitive  rules.  Default.  0 (disabled). 

■ badmailf rom:  list  of  sender  addresses  whose  emails  will  be  rejected.  A line  in 
badmailfrom  may  be  of  the  form  @host,  meaning  every  address  at  host. 

Default:  the  badmailfrom  file  is  absent  (all  sender  addresses  are  allowed);  See  also 

splithorizon. 

■ badmailpatterns:  the  same  as  standard  badmailfrom  but  with  patterns. 

Example: 

*@ear thlink.net 
! fred@earthlink.net 

[0-9]  [0-9]  [0-9]  [0-9]  [0-9] @ [0-9]  [0-9]  [0-9]  .com 
answerme@save* 

*9-*  . 

o , 


Default:  the  badmailpatterns  file  is  absent  (all  sender  addresses  are  allowed);  See 
also  splithorizon. 

■ badmailf rom-unknown:  if  the  domain  part  of  sender's  address  matches  a host  in 
this  list,  qmail  checks  if  sender's  IP  has  a PTR  record.  Example: 

http://www.lamer.de/maex/creative/software/qmail/103-bmfunk/badmailfrom- 

unknown.  Default:  the  badmailf  rom-unknown  file  is  absent  (reverse  DNS  check 
is  disabled  for  all  IPs). 
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■ badhelo:  filter  HELO/EHLO  sequence  issued  by  SMTP  client;  See  also 
splithorizon. 

■ badrcptto:  list  of  recipient  addresses  for  which  all  mail  is  blocked.  A line  in 
badrecipient  may  be  of  the  form  @host,  meaning  every  address  at  the  host. 

Default:  the  badrcptto  file  is  absent  (no  recepient  addresses  are  blocked). 

■ badrcptpatterns:  the  same  as  badrcptto  but  with  patterns.  It  allows  qmail-smtpd 
to  reject  SPAM  E-Mail  including  the  signature 

*\ [dd.dd.dd.dd\] * 

in  the  badrcptpatterns  file,  where  dd.dd.dd  is  the  IP  address  in  brackets.  Default:  the 
badrcptpatterns  file  is  absent  (no  recipient  addresses  are  blocked). 

■ biackhoiedsender:  the  same  as  badmailpatterns  but  quits  the  session 
immediately  even  if  quitasap  is  disabled. 

■ relayclients:  list  of  IP  addresses  of  clients  allowed  to  relay  mail  through  this 
host.  Addresses  in  relayclients  may  be  wildcarded: 

192.168.0. 1: 

192.168.1. : 

Default:  the  relayclients  file  is  absent  (all  client  IPs  are  allowed  to  relay  mail  via  this 
host). 

■ relaydomains:  list  of  host  and  domain  names  allowed  to  relay  mail  through  this 
host.  This  is  an  additional  mail  relay  check  by  the  domain  name,  in  case  if  relay  via 
the  tcp.cdb  static  relay  database  is  forbidden.  More  on  mail  relays  read  in  Parallels 
H-Sphere  Service  Administrator  Guide,  SMTP  Mail  Relays  section. 

Addresses  in  relaydomains  may  be  wildcarded: 

heaven . af .mil : 

. heaven .af.mil: 


Default:  the  relaydomains  file  is  absent  (all  domains  are  allowed  to  relay  mail). 

■ relaymailf  rom:  list  of  senders  ("Mail  From:")  allowed  to  relay  independently  even 
if  open  relay  is  closed.  Entries  in  relaymailfrom  can  be  E-Mail  addresses,  or  just  the 
domain  (with  the  @ sign).  Unlike  relaydomains,  native  addresses  should  be 
entered.  Examples: 

j oeblow@domainl . com 
@domain2 . com 

Default:  the  relaymailfrom  file  is  absent  (no  senders  are  allowed  to  relay 
independently). 

Important:  For  antispam  security  reasons,  we  strongly  recommend  not  to  add  this 
parameter  to  SMTP  configuration. 

■ quitasap:  enables  (1 ) or  disables  (0)  quitting  of  SMTP  session  immediately  if  one 
of  the  above  rules  works.  Default:  0 (no  quitting).  Enabling  this  option  is 
recommended  only  in  case  of  spam  attacks  or  huge  spam  traffic  to  your  server.  If 
working,  quitasap  breaks  SMTP  connection  if  at  least  one  of  the  following 
parameters  is  enabled,  the  result  of  its  check  being  negative: 

■ SPF  check 

■ smdcheck 
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■ mfdnscheck 

■ no  openrelay  for  sender  IP 

■ badmailfrom 

■ badmailfrom-unknown 

■ badrcptto 

■ userchk 

■ maxrecipients 

■ smtpauth 

■ antivirus 

■ antispam 

■ badhelo 

■ helodnscheck 

Use  the  quitasap  option  with  precaution  as  breaking  of  SMTP  connection  is  contrary 
to  the  requirements  of  correct  SMTP  server  operation. 

■ tarpitcount:  the  number  of  recipients  after  which  qmail  switches  on  delay  before 
sending  the  message  to  the  next  portion  of  recipients. 

Default:  0 (no  tarpitting); 

■ tarpitdelay:  the  time  in  seconds  of  delay  to  be  introduced  after  each 
subsequent  RCPT  TO:.  Default:  5. 

■ mfdnscheck:  enables  (1 ) or  disables  (0)  DNS  check  of  domain  name  in  sender's 
address.  If  enabled,  no  local  domain  check  is  performed. 

Default:  0 (disabled); 

■ nomfdns check:  list  of  domain  names  that  aren't  checked  for  existence.  The  list 
has  the  same  format  as  for  relaymailfrom.  Default:  the  nomfdnscheck  file  is  absent 
(if  mfdnscheck  is  enabled,  all  domains  are  checked  for  existence); 

■ helodnscheck:  in  a manner  similar  to  mfdnscheck,  performs  check  for 
HELO/EHLO  smtp  commands  instead  of  RCPT  TO:.  See  also  splithorizon. 

■ splithorizon:  if  1 , helodnscheck,  badhelo,  badmailfrom,  and  badmailpatterns 
checks  for  SMTP  sessions  with  open  relay  mfdnscheck  are  not  performed. 

■ userchk:  enables  (1 ) or  disables  (0)  check  that  the  vpopmail  recipient  is  valid 
before  accepting  the  message.  Default.  0 (disabled); 

■ smdcheck:  allows  only  local  domains  in  the  MAIL  FROM  address  if  mail  is  sent 
remotely.  If  the  option  is  enabled,  SMTP  is  used,  otherwise  - Sendmail  is. 

Default:  0 (any  sender  address  is  allowed). 

■ authsender:  if  set  to  1 , it  requires  the  domain  name  in  user  address  during  SMTP 
authentication  to  coincide  with  the  domain  name  in  the  MAIL  FROM  address  field. 

a By  default:  'O'  if  smtpauth  parameter  is  OFF. 

■ By  default:  '2'  if  smtpauth  parameter  is  ON. 

Note:  value  '2'  is  used  as  additional  procedure  providing  correct  traffic  calculation  in 
case  of  dynamic  open  relay.  In  this  case , instead  of  recording  mail  envelop  sender 
domain,  traffic  log  records  the  domain  used  in  SMTP  authentication). 

■ rbihosts : RBL  (Remote  Black  List)  database  hosts.  Example: 
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dnsbl.njabl.org 
spamguard . leadmon . net 


Allowed  anti-RBL  source  addition  (http://cr.yp.to/ucspi-tcp/rblsmtpd.html).  Format  of 
anti-RBL  source  : a : domainname . Default : the  rbihosts  file  is  absent  (RBL  check 
is  disabled:  no  external  RBL  databases  is  being  checked). 

Note  1 : Parallels  H-Sphere  Qmail  MTA  is  built  with  "A"  record  patch,  so  it's  possible 
to  enable  DNSBL,  which  doesn't  support  "TXT"  DNS  records.  For  instance,  Trend 
Micro  Network  Reputation  Services  DNSBL 
(http://us.trendmicro.com/us/products/enterprise/network-reputation- 
services/index.html).  You  can  enable  its  support  via  Mail  Service  Settings  in  the 
Admin  CP.  At  the  moment,  you  can  do  it  by  adding  the  string: 

"activationcode . r .mail-abuse . com: blocked  using  Trend  Micro 
RBL+,  please  see  http://www.mail-abuse.com/cgi- 
bin/lookup?ip  address=%IP%" 

Note  2: 

a Quotation  marks  are  necessary. 

b For  commercial  RBL,  like  Trend  Micro  RBL+ 

(http://us.trendmicro.com/us/products/enterprise/network-reputation- 

services/index.html),  after  the  service  is  rendered,  the  corresponding  value 
Should  be  set  instead  Of  activationcode. 

■ qmaiispp : Enables  Qmail  plugin  support.  Default:  0 (disabled). 

■ f lagf ailciosed:  Always  consider  dns  lookups  failure  as  a temporary  error,  451 . 
Default:  0 (disabled). 

■ f lagrbibounce:  Consider  RBL  error  status  code  as  a fatal  (553),  instead  of 
default  policy,  temporary  error  (451).  Default:  0 (disabled). 

■ strictheiocheck  parameter  (options  file,  disabled  by  default),  which  considers 
PIELO  command  obligatory. 

■ chksignature : (options  file),  which  provide  badsignatures  filtering  for  mail 
resources  with  enabled  antivirus  check.  Default:  0 (disabled). 

■ chkioadertype:  (options  file),  which  provide  badloadertypes  filtering  for  mail 
resources  with  enabled  antivirus  check.  Default.  0 (disabled). 

Both  chksignature  and  chkioadertype  include  a wire-speed  filtering  of  E-Mails 
containing  BASE64  encoded  attachments  with  about  99,5%  efficiency: 

http://www.fehcom.de/qmail/docu/virus  2004.pdf 
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Note:  chksignature  provides  a 

Note:  chkloadertype  provides  a 

robust  MIME  type  identification. 

high  efficient  and  unique  Loader 

Particular  MIME  types  can  be 

type  recognition.  Though  this 

added  on-the-fly  (based  on  the 

procedure  is  more  heavy,  than 

idea  of  Russell  Nelson's  (and 

signature  check  and  is  less 

Charles  Cazabon's)  to  filter 

recommended.  Predefined 

Windows  executables  attached  as 

loadertype  check  is  oriented  on  the 

BASE64  encoded  MIME  parts  in 

Kernel32.dll  search  (specific 

the  E-  Mail.  Included  the  following 

Loader  types  for  the  Windows  OS 

signatures,  which  detect  specific 

are  included  in 

common,  double  and  triple  Base 

control/badloadertypes) : 

64  Windows  Executable 

Mi  5 kb 

(control/badsignatures): 

MzluZ 

TVqQAAMAA 

MyLmR 

TVpQAAIAA 

MyLkR 

TVpAALQAc 

Mi5ET 

TVpyAXkAX 

My51e 

TVrmAU4AA 

TVrhARwAk 

TVoFAQUAA 

TVoAAAQAA 

TVoIARMAA 

TVouARsAA 

TVrQAT8AA 

TVrvAEQAe 

UEsDBAoAA 

VFZxUUFBT 

VkZaeFWR 

ZGItIGZpb 

Note:  The  list  of  signatures  is  static,  not  configurable  via  CP  interface.  If  you  want  to 
add  something,  you  should  edit  the  corresponding  control  files:  badloadertypes  and 
badsignatures. 

• sms:  Restriction  of  Max  messages  for  one  email  value  for  Mail  SMS  resource  (Max 
value:  3).  Default:  3. 

• spamgiobai:  Antispam  check  of  all  incoming  mail.  Default:  0 (disabled). 

■ clamgiobai:  Antivirus  check  of  all  incoming  mail.  Default:  0 (disabled). 

■ skipcachk:  ClamAV  (Antivirus  Filter)  check  restriction.  Default:  0 (disabled). 

■ skipsachk:  Spamassassin  (AntiSpam  Filter)  check  restriction.  Defaults 
(disabled). 

■ periplimit:  enter  the  number  of  simultaneous  SMTP  connections  from  the  same 
IP. 
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■ noathost:  demands  fully  qualified  domain  email  address  in  RCPT  TO  and  MAIL 
FROM  smtp  commands.  Default.  0 (disabled).  If  you  enable  this  parameter,  you  will 
never  get  reject/bounce  messages,  or  return  receipts,  and  you  may  get  other  mail 
server  admins  upset  at  you  if  they  have  to  deal  with  your  bounce  messages.  Since 
this  is  contrary  to  the  requirements  of  correct  SMTP  server  operation  (Mailservers 
are  required  by  RFC1 123  5.2.9  to  accept  mail  from  "<>"),  use  noathost  parameter 
with  precaution. 

■ sanetcheck:  enables/disables  network  check  for  SpamAssassin.  Default:  0 
(disabled).  By  default,  SpamAssassin  performs  only  local  tests.  By  enabling  this 
parameter  you  can  also  enable  network  tests  for  SpamAssassin,  such  as 
DCC_CPIECK  (Distributed  Checksum  Clearinghouse  is  an  anti-spam  content  filter), 
URIDNSBL  (look  up  URLs  found  in  the  message  against  several  DNS)  etc.  These 
network  test  use  internet  resources.  Network  tests  must  be  set  in  the  additional 
configuration  file 

(/hsphe  re /local/  con  fig/mail/  spamass  as  sin/ custom,  cf).  A path  to  this 
file  is  set  via  the  include  directive  of  the  main  SpamAssasin  local. cf  file.  Use  this 
additional  configuration  file  for  plugins  and  options  of  SpamAssassin. 

■ spamdchiidren:  specifies  the  number  of  forked  spamd  child  processes.  Default: 
10.  We  recommend  to  increase  it  for  servers  with  large  number  of  smtpd 
connections. 

■ rcptdns checks:  allows  only  existing  mail  domain  names  of  recipients.  Default:  0 
(off). 

■ uquotacheck:  provides  message  bouncing  during  SMTP  session  in  case  of 
mailbox  quota  overflow.  Default:  0 (off). 

■ localtime:  provides  generation  of  date  stamps  in  local  timezones  for  various 
qmail  programs.  Default:  0 (off). 

■ samsgsize:  maximum  message  size,  in  bytes  to  be  send  to  spamd. 

■ catchall:  provides  ability  to  disable  the  work  of  'Catch  AH'  options  independently 
of  user  settings.  Default:  1 (enabled). 

■ re  j ectdiscardedmaii:  rejects  incoming  messages  to  mailboxes  with  discard 
option  at  SMTP  level.  Default:  0 (disabled). 

■ skipsachk,  skipcachk:  skip  Spamassassin  (SA)/Antivirus  (CA)  check: 

■ skipcachk=0  and/or  skipsachk=0  or  absent:  default  settings  - always  CA 
and/or  SA  check,  if  enabled 

■ skipcachk=1  and/or  skipsachk=1 : for  SMTP  authenticated  users  CA  and/or 
SA  heck  skipped 

■ skipcachk=2  and/or  skipsachk=2:  for  SMTP  connections  with  dynamic  or 
static  open  relays  or  for  SMTP  authenticated  users  CA  and/or  SA  check  skipped 

Note:  As  an  example  of  patterns,  see  the  canonical  method  filter  for  spam  e-mail  in 
README_SPAMCONTROL 

(http://www.fehcom.de/qmail/spamcontrol/README  spamcontrol.html). 
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Mail  Client  Headers 

x-Originating-iP  and  x-Enveiope-To  mail  client  headers  are  included  in 
Parallels  H-Sphere  by  default.  They  introduce  the  following  controls: 

■ xoriginatingip:  includes  X-Originating-IP  header  into  mail  client  according  to 
AOL  recommendations,  http://postmaster.aol.com/fag/forwardinq.html  (enabled  by 
default) 

■ xenveioptoheader:  includes  X-Envelope-To  header  which  is  required  by  some 
mail  clients  to  identify  real  envelope  sender  (disabled  by  default) 


Autoresponder  Settings 

Parallels  H-Sphere  provides  autoresponder  policy.  Enter  the  necessary  parameters  and 
click  Submit: 


Autoresponder  settings 

patterns jx)l  icy  Q 

F i/o 

(*  Autoresponder  works  only  if  Sender  Filter  is  set  in  user  CP) 

autoreply_policy  Q 

1 Check  domain  sender  on  IP  level  j^| 

Common  behaviour 

Check  domain  sender  on  subnet  level 

L 

| Check  domain  sender  on  IP  level 

■ patterns_poiicy  - autoresponder  is  working  only  if  Sender  Filter  is  configured 
in  user  CP.  The  default  value  is  0 (disabled). 

■ autorepiy_poiicy  - provides  autoreply  if  SENDER  originating  IP  corresponds  to 
a target  receipient  IP  or  Subnet  only 
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Bounce  Message  Customization 

Parallels  H-Sphere  enables  bounce  and  doublebounce  messaging  in  case  mail  failed  to 
be  delivered.  Enter  the  necessary  parameters  and  click  Submit: 

■ bouncingip:  parameter  removed  in  Parallels  H-Sphere  3. 0 RC  2,  added  a 
separate  Outgoing  IP  to  mail  server.  Once  you  add  it  via  Admin  CP,  it  will  disappear 
from  Qmail  parameters. 

■ bouncef  rom:  the  email  user  messages  are  bounced  from.  Default:  MAILER- 
DAEMON; 

■ bouncehost:  the  literal  name  or  bouncehost  IP.  If  a message  is  permanently 
undeliverable,  qmail-send  sends  a single-bounce  notice  back  to  the  message's 
envelope  sender,  from:  bouncefrom@bouncehost.  Default:  mail  server  name. 

■ doubiebouncehost:  the  literal  name  doublebouncehost  or  IP.  If  a single-bounce 
notice  is  permanently  undeliverable,  qmail-send  sends  a double-bounce  notice  to 

doubiebounceto@doubiebouncehost.  Default:  mail  server  name. 

■ doubiebounceto:  the  user  email  to  receive  doublebounce  messages. 

■ bouncesubject:  enter  bounce  message  subject. 

■ bouncemessage:  enter  the  text  of  the  bounce  message. 

■ doubiebouncesub  j ect:  enter  doublebounce  message  subject. 

■ doubiebouncemessage:  enter  the  text  of  the  doublebounce  message. 

■ temperror:  considers  temporary  error  a permanent  one  for  local,  remote,  and 
local  & remote  mails. 

■ strictbounce:  strictbounce  allows  for  bounce  to  act  as  double  bounce  and  for 
bounce  and  double  bounce  to  act  as  triple  bounce  (when  bounce  message  is 
discarded). 

Mail  Protocols 

Choose  a system  SMTP  relay  for  your  mail  server  - POP  before  SMTP  and  SMTP 
AUTH. 

■ smtpauth:  enables  SMTP  AUTH  extension 

Default:  0 (AUTH  LOGIN/PLAIN/CRAM-MD5  SMTP  extension  is  disabled) 

■ popbef oresmtp:  enables  POP-BEFORE-SMTP 

■ opensmtptimeout:  allows  to  set  open  relay  lifetime,  in  minutes,  after  POP-before- 
SMTP  authentication.  Default:  180  min. 
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SPF  (Sender  Policy  Framework) 

Parallels  H-Sphere's  SPF  (on  page  181)  implementation  at  the  SMTP  server  level  is 
based  on  this  qmail  patch:  http://www.saout.de/misc/spf/.  It  introduces  the  following 
qmail  controls: 

■ spfbehavior:  turns  SPF  checking  on/off.  The  default  value  is  0 (off).  You  can 
specify  a value  between  0 and  6: 

■ 0:  Never  do  SPF  lookups,  don't  create  Received-SPF  headers 

■ 1 : Only  create  Received-SPF  headers,  never  block 

■ 2:  Use  temporary  errors  when  you  have  DNS  lookup  problems 

■ 3:  Reject  mails  when  SPF  resolves  to  fail  (deny) 

• 4:  Reject  mails  when  SPF  resolves  to  softfail 

• 5:  Reject  mails  when  SPF  resolves  to  neutral 

■ 6:  Reject  mails  when  SPF  does  not  resolve  to  pass 
Values  bigger  than  3 are  strongly  discouraged. 

Important:  This  setting  can  be  overridden  using  the  environment  variable 
SPFBEHAVIOR,  e.g.  from  tcpserver  rules. 

Note:  If  RELAYCLIENT\s  set,  SPF  checks  won't  run  at  all.  (This  also  includes 
SMTP-AUTFI  and  similar  patches) 

■ spf  rules:  sets  a line  with  local  rules,  i.e.,  rules  that  are  executed  before  the  real 
SPF  rules  for  a domain  would  fail  {fail,  softfail,  neutral). 

They  are  also  executed  for  domains  that  don't  publish  SPF  entries. 

■ spf  guess:  sets  a line  with  guess  rules,  i.e.,  rules  that  are  used  if  the  domain 
doesn't  publish  SPF  rules.  The  local  spfrules  are  always  executed  afterwards. 

■ spf  exp:  customized  SPF  explanation.  The  explanation  is  the  line  returned  to  the 
SMTP  sender  when  a mail  is  rejected  at  the  SMTP  level.  You  can  use  macro 
expansion.  If  a domain  specifies  its  own  explanation  it  is  going  to  be  used  instead. 
The  SMTP  answer  when  rejecting  mails  will  look  like:  550  the  expanded  SPF 
explanation  (#5.7.1) 
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SRS  (Sender  Rewriting  Scheme) 

SRS  (on  page  181)  is  implemented  with  the  following  qmail  control  files  located  in  the 

/ var/ qmail/ control /srs  directory: 

■ revers_srs_secrets:  contains  keys  called  secrets  to  form  hash  for  SRS 
address  for  reverse  mail.  The  file  contains  the  list  of  secrets,  each  in  separate  line. 
The  most  recent  key  is  on  top  of  the  list.  Qmail  takes  it  first  when  checking  SRS 
address,  and  if  it  doesn't  fit,  Qmail  takes  these  keys  one  after  another.  If  none  fit, 
the  message  will  be  rejected.  The  file  has  400  permissions  and  vpopmaikvchkpw 
ownership. 

■ srs_secrets:  secrets  for  SRS  address  in  forwards.  The  file  has  400  permissions 
and  qmailkqmail  ownership. 

■ srs_secrets_age:  an  auxiliary  file  containing  information  when  each  key  in 
revers_srs_secrets  and  srs_secrets  was  created.  It  is  generated  by  the 

/ var /qmail /bin/  setsrssecret  script  and  consists  of  the  lines  in  the  following 
format: 

key  timestamp 

■ srs_max_age:  an  integer  value  (in  seconds)  for  the  maximum  permitted  age  of  a 
rewritten  address.  SRS  rewritten  addresses  expire  after  a specified  number  of  days 
after  which  it  is  assumed  no  more  bounces  may  be  generated  in  response  to  the 
original  mail.  Mail  sent  to  expired  SRS  address  is  dropped  without  ceremony.  The 
default  (about  a month)  should  be  appropriate  for  all  purposes. 

These  controls  are  initiated  and  set  by  running  the  /var/qmaii/bin/setsrssecret 
script.  You  can  run  this  script  also  as  cron  (on  page  33)  on  mail  servers. 

Read  more  about  SRS  qmail  controls  at  http://www.libsrs2.org/docs/index.html. 

Command  Line  Qmail  Configuration 

Qmail  installation  directory  is  usually  /var/qmaii/. 

SMTPd  configuration  files  are  also  called  control  files.  Each  SMTP  parameter  is 
configured  in  its  own  control  file  with  the  same  name,  for  example, 

/var/qmail/control/smtpauth  for  smtpauth  parameter. 

All  controls  are  placed  in  one  configuration  file,  /var/qmaii/controi/options. 

To  view  SMTP  server  configuration,  run  the  qmaii-showcti  utility,  under  root: 

# /var/qmail/bin/qmail-showctl 

You  will  get  the  list  of  SMTP  parameters.  Each  line  in  the  list  has  the  following  format: 

smtp^parameter : [(Default.)]  Value 

Each  stmp_parameter  may  be  set  in  its  own  control  file  with  the  same  name  located  in 
the  /var /qmail /control  directory..  The  file  contains  the  parameter's  value.  If  the 
file  is  not  found,  the  default  value  is  taken  and  the  default  notification  (Default . ) 
shows  up  in  the  configuration  list. 
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Syslog  Facility/Level  Configuration  For  rblsmtpd 

rblsmtpd  is  a generic  tool  to  block  mail  from  RBL-listed  sites.  It  is  located  in 

/hsphere/ shared/bin/ rblsmtpd. 


It  is  possible  to  customize  syslog  facility/level  settings  for  rblsmtpd  to  redirect  messages 
to  custom  log  files.  The  following  facilities/levels  are  customizable  (read  man  3 
syslog  for  details): 


Facilities 

Levels 

LOG  AUTH 

LOG  AUTHPRIV 

LOG  CRON 

LOG  DAEMON 

LOG  FTP 

LOG  KERN 

LOG  LOCALO  . . . 

LOG  LOCAL 7 

LOG  LPR 

log  mail  (default) 

LOG  NEWS 

LOG_SYSLOG 

LOG  USER 

LOGJJUCP 

LOG  EMERG 

LOG  ALERT 

LOG  CRIT 

LOG  ERR 

LOG  WARNING 

log  notice  (default  for 

FreeBSD) 

log  info  (default  for  Linux) 

LOG  DEBUG 

Custom  facility/level  records  are  set  in  the  /var/qmaii/controi/rbisysiog  file, 
for  example: 

LOG_LOCAL7  : LOG_WARNING 

Also  you  must  add  the  respective  record  in  /etc/sysiog . conf  (see  man 
syslog.  conf  for  details)  to  redirect  messages  to  a new  log  file,  for  example: 

local7.warn  /var/log/myrbllog 

File  /var/ qmaii/ control/ sysfacility  contains  name  of  syslog  facility  (one  from 
among  log_localo  . . . log_local7)  used  to  gather  mail  traffic  statistics  (on  page 
192). 
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SMTP  Log 

Maillog  format  is  extended: 

■ remote  IPs  of  SMTP  sessions  are  logged  by  default; 

■ smtplog  parameter  is  introduced  in  the  /var/qmail/control/options  file: 

■ 0 default  logging  mode 

■ 1 : restricted  mode  of  SMTP  session  logging 

■ 2:  complete  SMTP  logging 

This  parameter  is  not  included  in  CP  and  is  not  modified  in  admin  interface,  as  it 
serves  for  debug  purpose  only. 


Mail  Client  and  ESMTP  Destination  Server 

Mail  client  can  check  if  the  following  extensions  are  available  on  the  destination  server 
and,  if  so,  use  them. 

■ ESMTP  STARTTLS  extension  defined  in  RfC  RFC3207 

■ ESMTP  SIZE  extension  defined  in  RfC  1870 

■ ESMTP  PIPELINING  extension  defined  in  RfC  2920 

By  default,  only  esmtp  size/pipelining  check  is  provided  if  destination  server 
supports  them. 

Switching  over  qmaii-remote  client  to  use  them  is  made  via  mconnectext  control 
file  with  content  of  the  following  format: 

iii 

where  i equals  0 or  l and 

■ First 'i' corresponds  to  STARTTLS 

■ Second  'i'  corresponds  to  SIZE 

■ Third  'i'  corresponds  to  PIPELINING 
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Qmail-spp  Support 

Parallels  H-Sphere  adds  a qmail-spp  engine  (http://qmail-spp.sourceforqe.net/)  which 
provides  plugin  support  to  qmail's  SMTP  daemon  (qmail-smtpd).  It's  written  entirely  in 
C using  native  qmail  libraries,  so  it  does  not  create  any  dependencies.  Qmail-spp 
engine  implementation  is  aimed  to  add  rbispp  plugin  as  a replacement  for  rbismtpd. 

To  make  the  server  and  plugins  work  faster,  follow  the  rules: 

■ Use  the  engine  only  as  circumstances  may  require,  i.e.  to  add  new  plugins 

■ Do  not  run  plugins  via  system  shell,  that  means  without  adding  just  before  plugin 
path.  Avoid  command  line  parametres  or  plugins  written  on  shell/perl 

■ Use  full  pathes  to  plugins 

■ Accumulate  functionality  in  one  particular  plugin  rather  than  use  different  plugins 

Configuration  Details 

Qmail-spp  support  can  be  enabled  via  CP  interface  and  configured  in 

/var/ qmail/ control/ options  file  (qmailspp  boolean  parameter).  When  qmail-spp 

engine  is  involved,  qmail-smtpd  tries  to  read  the  main  default  configuration  file  of  qmail- 

spp  /var/qmaii/ control/ smtppiugins  that  consists  of  few  sections  one  for  each 

command: 

connection  - for  plugins  run  just  after  client  connection 

helo  - for  HELO/EHLO 

mail  - for  MAIL 

rcpt  - for  RCPT 

data  - for  DATA 

auth  - for  AUTH 

Mind  that  you  have  to  specify  full  pathes  to  plugins  while  configuring  qmail-spp.  To  find 
more  info  on  syntax,  refer  to  qmail-spp  documentation  (http://qmail- 
spp.sourceforge.net/doc/). 

To  add  plugins  to  conf  file,  use  the  following  utility: 

/var/qmail/bin/spp-conf  -h 

Usage: 

-a|-r|-R  -h  -b  -s  -p  plugin  name  -t  category  name 

plugins  must  be  located  at  /var/qmail/control/plugins  directory. 

plugin  name:  relative  plugin  name 

category  name:  connection,  auth,  helo,  mail,  rcpt,  data 
-a  : add  plugin  (by  default) 

-r  : remove  plugin 
-R  : remove  all  plugins 

-b  : input  from  stdin  set  of  rows,  format:  category_name;plugin  name 
-s  : plugin  is  executed  via  shell  -i  : check  and  fix  plugin  permissions 
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Qmail  TLS  Support 

In  mail  service  configured  with  SSL,  TLS  is  disabled  by  default  (maii-ssi-proto 
script  was  used  to  switch  it  on). 

To  enable  TLS  support  (with  possible  protocols:  SSLv2,  SSLv3,  TLSvl,  by  default 
SSLv3  only),  run: 

/hsphere/local/config/mail/scripts/mail-ssl-proto  -r  -t  SSLv3, TLSvl 

Where: 

■ maii-ssi-proto  script  sets  list  of  SSL  protocols  used  by  mail  service. 

■ -r  provides  mail  service  restart. 


Integrated  Plugins 

Rblspp  Plugin 

Rblspp  plugin  was  added  as  a replacement  for  rbismtpd.  It  resolves  the  RBL  check 
delay  problem  for  successful  SMTP  authenticated  connections.  For  this,  ucspi-tcp- 
0 . 88-rbispp.patch  patch  was  combined  with 

(http://xs3.b92.net/tomislavr/qmail.html#ii)  ifauthskip . c,  and  command  line 
parametres  were  removed  to  speed  up  the  plugin  launch. 


If  RBL  check  is  involved  but  plugin  support  is  disabled,  default  rbismtpd  scheme  is 
used. 
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Choosing  Remote  MySQL  Logical  Server 
for  SpamAssassin 

Parallels  H-Sphere  mail  logical  server  is  by  default  installed  on  a physical  box  together 
with  Web  and  MySQL  servers  on  the  same  box,  thus  SpamAssassin  uses  MySQL 
database  on  the  same  server. 

It  is  made  possible  to  choose  an  alternative  remote  MySQL  server  for  SpamAssassin 
database.  This  is  in  particular  important  for  the  implementation  of  load  balanced  mail 
cluster  (on  page  406)  where  it  is  required  that  SpamAssassin  is  configured  to  use 
remote  MySQL  servers. 

> To  choose  a remote  remote  MySQL  server  for  SpamAssassin: 

1 Login  as  cpanel  user  (on  page  65)  and  set  the  following 
property  in 

~ cpanel / shiva/ psof t_conf ig/h sphere .properties  : 
EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  54)  to  apply  changes. 

Important:  If  EXTERNAL  SERVICE  USAGE  is  not  set  or  is  not  TRUE,  you  won't 
be  able  to  choose  an  external  MySQL  server  for  SpamAssassin! 

2 In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to 
settings  for  this  mail  logical  server,  and  select  a MySQL  server  from 
the  Choose  External  Spamassassin  DB  Server  dropdown  menu  in  Mail 
Server  Additional  Options . 

3 Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 

hspackages  reconfig=spamassassin 

Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 

4 To  move  SpamAssassin  DB  content  from  the  older  local  MySQL  DB, 
run  the  following  script  on  the  source  box: 

/hsphere/pkg/ scripts/uprocedures/dbs_content  -h 
Usage: 

dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 

dbtype:  horde  or  spamassassin  or  phpmyadmin 

ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the 
corresponding  mail  logical  server. 


Mail  System 


181 


password:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding 
mail  logical  server. 


SPF  and  SRS 


Sender  Policy  Framework  (SPF)  (http://spf.pobox.com/)  is  a mechanism  for 
preventing  sender  forgery  in  SMTP  transaction,  thus  allowing  domain  owners  control 
over  who  may  send  mail  from  their  domain. 

Sender  Rewriting  Scheme  (SRS)  (http://spf.pobox.com/srs.html)  is  a mechanism  for 
rewriting  sender  addresses  when  a mail  is  forwarded  in  such  a way  that  mail  forwarding 
continues  to  work  in  an  SPF  compliant  world. 

SRS  can  work  without  SPF,  but  not  vice  versa,  i.e.,  issues  with  forwards  may  arise  if 
SPF  is  implemented  without  SRS. 


WARNING:  If  SRS  is  enabled  in  Parallels  Pi-Sphere,  the  problems  may  arise  with 
forwarding  mail  to  servers  where  SRS  is  not  supported.  In  such  cases,  mail  may  return 
undelivered  back  to  users.  The  next  Parallels  Pi-Sphere  mail  service  package  will 
provide  a more  friendly  way  to  handle  forwards  to  such  servers. 


This  documentation  explains  the  arrangement  of  these  resources  at  the  server  level. 
Please  read  how  to  enable  and  configure  SPF  and  SRS  in  admin  CP  in  Parallels  H- 
Sphere  Service  Administrator  Guide. 

In  this  section: 


SPF  (Sender  Policy  Framework) 182 

SRS  (Sender  Re-write  Scheme) 183 
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SPF  (Sender  Policy  Framework) 

SPF  is  implemented  at  the  level  of: 

■ DNS  TXT  records 

■ SMTP  server. 

DNS  TXT  Records 

Once  the  SPF  resource  is  enabled  in  Parallels  Pi-Sphere,  DNS  TXT  records  will  be 
provided  for  each  A and  MX  records  in  E.Manager->DNS  Manager. 

DNS  TXT  records  have  the  following  format: 

domain.com  IN  TXT  "v=spfl  spf_string" 

Plere,  spf  l is  SPF  version,  and  spf_string  takes  the  combination  of  the  so-called 
mechanisms:  "a,  ptr,  mx,  ip4,  include,  all",  all  is  a finalizing 
mechanism  and  must  be  placed  at  the  end. 

Please  read  more  explanations  on  mechanisms  in  TXT  DNS  records 
(http://spf.pobox.com/mechanisms.html). 

Each  mechanism  may  have  a prefix  pointing  to  a certain  type  of  processing  messages: 

■ - fail  (message  is  rejected) 

■ ~ softfail  (message  is  passed  with  warning) 

■ + pass  (message  is  passed  - the  default  prefix  value) 

? neutral  Thus,  the  simplest  SPF  record  will  be: 

domain.com  IN  TXT  "v=spfl  -all" 

It  means  that  you  deny  sending  any  mail  from  this  domain,  i.e.,  you  may  use  this 
domain  for  any  hosting  except  mail  hosting,  (-all  is  thus  somewhat  similar  to  deny  all  in 
Apache). 

Example: 

Consider  the  following  record: 

domain.com  IN  TXT  "v=spfl  mx  a : test . com/24  ptr : test2 . com  -all" 

If  a message  is  sent  with  MAIL  FROM:  test@test3 . com  and  from  the  client  IP 
4. 5. 6. 7,  SMTP  server  will  check: 

a whether  test3.com  MX  records  (at  least  one  of  them)  are  resolved  to  IP  4.5. 6.7; 
b whether  the  IP  4.5. 6. 7 is  in  a test.com's  IP  subnet  (mask  255.255.255.0); 
c whether  the  PTR  record  for  IP  4. 5. 6. 7 is  resolved  to  test2.com; 

If  none  of  the  above  conditions  are  met,  then  the  last  directive  -all  meaning  "deny 
all  other"  takes  effect,  and  the  message  will  be  rejected. 

The  include  directive  is  used  if  you  wish  to  delegate  SPF  check  for  another  domain, 
for  example: 
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"v=spfl  include : example . net  -all" 

SMTP  Server 

At  the  level  of  qmail  server,  the  following  SMTP  parameters  should  be  configured  in 
respective  files  in  /var/qmaii/controi  directory: 

■ spfbehavior 

■ spfrules 

■ spfguess 

■ spfexp 

For  more  details,  refer  to  Qmail  Configuration  (on  page  160)  and  SPF  Implementation 
for  Qmail  (http://www.saout.de/misc/spf/). 


SRS  (Sender  Re-write  Scheme) 

SRS  mechanism  is  used  in  two  cases: 

■ To  form  SRS-compliant  mail  address  for  forwarding  messages  via  forward  mail 
resources,  in  accordance  with  SRS  convention; 

■ To  form  reverse  SRS-compliant  reverse  mail  address  in  case  of  reply. 

Parallels  Pi-Sphere  provides  the  following  Qmail  controls  for  SRS  (they  are  located  in 

the  /var/qmail/control/srs/  directory): 

■ SRS  secrets  files:  reverse_srs_secrets  (for  reverse  mail)  and  srs_secrets 
(for  forwards).  These  files  contain  a set  of  lines  with  keys,  each  key  in  a separate 
line.  These  keys,  called  secrets,  are  used  to  validate  hash  from  SRS  formatted  e- 
mail  address.  The  most  recent  key  is  on  top  of  the  list.  Qmail  takes  it  first  when 
checking  SRS  address,  and  if  it  doesn't  fit,  Qmail  takes  these  keys  one  after 
another.  If  none  fit,  the  message  will  be  rejected. 

The  revers  srs  secrets  file  has  400  permissions  and  vpopmaikvchkpw 
ownership. 

The  srs  secrets  file  has  400  permissions  and  qmailkqmail  ownership. 

■ srs_maxage  - an  integer  value  for  the  maximum  permitted  age  of  a rewritten 
address.  SRS  rewritten  addresses  expire  after  a specified  number  of  days  after 
which  it  is  assumed  no  more  bounces  may  be  generated  in  response  to  the  original 
mail.  Mail  sent  to  expired  SRS  address  is  dropped  without  ceremony.  The  default 
(about  a month)  should  be  appropriate  for  all  purposes. 

For  details,  please  refer  to  http://www.libsrs2.org/docs/index.html. 


The  script  /var/qmaii/bin/setsrssecret  runs  as  cron  (on  page  33)  on  mail 
servers  to  set  these  controls. 
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Updating  SpamAssassin  Rulesets 
Automatically 

Below  are  two  scripts  used  for  automatical  update  of  SpamAssassin  rulesets. 

In  this  section: 


Sa-update  Script 184 

Rules  Du  Jour  Script 185 


Sa-update  Script 

Sa-update  (http://saupdates.openprotect.com/)  is  a script  aimed  at  the  dynamic  update 
of  basic  spam  assassin  rules  to  catch  different  kind  of  spam.  It  provides  a possibility  to 
add  other  channels,  but  at  your  own  risk. 

By  default  sa-update  script  is  located  at: 

■ /hsphere/local/conf ig/mail/spamassassin/sa-update-keys  - pgp 

key-rings.  It  is  automatically  formed  in  the  post  install  section  for  default  chanel. 

■ /hsphere/ local/ conf  ig/mail/ spamassassin/ sa-update  - directory 
where  updated  rules  are  located. 

The  /hsphere/local/conf  ig/mail/  spamassassin /scripts/  saupdate  script 
that  updates/checks  for  new  rules  can  be  customized  according  to  your  own  needs  by 
adding  new  rules.  This  script  remains  untouched  after  further  hsphere-mail-service 
updates. 
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Rules  Du  Jour  Script 

RulesDuJour  (http://www.exitQ.us/index.php?paqename=RulesDuJour)  is  a bash  script 
aimed  at  automatical  download  of  new  versions  of  SpamAssassin  rulesets  as  the 
authors  release  new  versions.  As  FreeBSD  does  not  include  bash  by  default,  Parallels 
H-Sphere  mail  service  package  containing  RulesDuJour  also  includes  the  bash 
installation  for  FreeBSD.  This  script  must  run  daily  as  a cron  task  to  keep  additional 
custom  SpamAssassin  rules  up  to  date. 

At  the  mail  server  level,  RulesDuJour  is  implemented  by  the  following  scripts: 

■ Initialization  script: 

/hsphere/local/conf ig/mail/spamassassin/scripts/init  rules  du 
j our 

■ Deletion  script: 

/hsphere/ local/ conf ig/mail/ spamassassin/ scripts /del ete_rules_d 
u_j  our 

■ RulesDuJour  SA  ruleset  update  script: 

/hsphere/local/conf ig/mail/spamassassin/scripts/rules  du  jour 


In  this  section: 


Initialization  Script 185 

Configuration  File 186 


Initialization  Script 

Initialization  script  is  launched  upon  enabling  the  Automatic  Ruleset  Update  (Rules  Du  Jour) 
option  in  SpamAssassin  Manager  via  the  administrator  control  panel: 

1 It  creates  the  default  RulesDuJour  config  file 

/hsphere/local/conf  ig/mail/spamassassin/rulesduj  our  . The  init 
script  syntax  (run  it  with  the  -h  option  to  get  help): 

# 

/hsphere/local/ conf ig/mail/ spamassassin/ scripts/ini t_rules_du_ 
jour  -h 

Usage: 

init  rules  du  jour  [ -r  rulesets  ] [ -e  email  ] 

rulesets:  list  of  comma  separated  ruleset;  possible  values: 

TRIPWIRE  EVILNUMBERS  SARE_RANDOM  (default:  all) 

email:  address  where  e-mail  notifications  on  SA  rulesets 

update  go  (default:  none) 

The  script  is  used  to  set  values  for  SA  rulesets  to  be  updated  and  the  e-mail 
address  where  update  notifications  will  be  sent.  See  Configuration  File  for  details. 

2 It  adds  the  RulesDuJour  SA  ruleset  update  script 

/hsphere/local/ conf ig/mail/ spamassassin/ scripts/ rules_du_j  our 

to  mail  server  cron  jobs  (on  page  33)  starting  daily  at  1 :00  AM: 


186 


Mail  System 


0 1*** 

/hsphere/local/ config/mail/ spamassassin/ scripts/rules_du_jour 


Configuration  File 

Initialization  forms  the  RulesDuJour  config  file 

/hsphere/local/ config/mail/ spamassassin/ rulesdu j our.  It  has  the 

following  format: 

# cat  rulesdu j our . default 

TRUS TED_RULE SET S=" TRIPWIRE  EVILNUMBERS  SARE_RANDOM" 

SA  D I R=/ hsphere/local/ config/mail/ spamassassin 
EMAIL_RDJ_UPDATE_ONLY= 

SINGLE_EMAIL_ONLY=true 

MAIL_ADDRESS= 

SA  LINT=" /hsphere/shared/bin/spamassassin  --lint" 

SA  RESTART=" /etc/rc . d/init . d/spamd  restart" 

TMPDIR=" $ { SA_DIR} /RulesDuJour" 

This  sample  config  file  is  for  Linux  servers.  For  FreeBSD,  it  has  a different  spamd 
restart  format: 

SA  RESTART=" /usr/ local /etc/rc . d/spamd . sh  restart" 

Two  config  files  variables  - trusted_rulesets  and  mail_address  - can  be  set  by 
the  init  script  and  via  Control  Panel  at  the  SpamAssassin  Manager  page: 

■ TRUSTED_RULESETS  - choose  under  what  categories  custom  rulesets  need  to 
be  included  and  updated: 

■ BLACKLIST  a blacklist  of  spammers. 

■ BLACKLIST_URI  looks  for  these  domains  inside  URL's  in  the  message. 

■ BOGUSVIRUS  lists  bogus  virus  warnings  and  similar. 

■ RANDOMVAL  list  of  tags  spammers  sometimes  forget  to  convert  in  spam. 

■ SARE_ADULT  designed  to  catch  spam  with  "Adult"  material. 

■ SARE_BAYES_POISON_NXM  using  lists  of  words  with  equal  length. 

■ SARE_BML  designed  to  catch  "business,  marketing  and  educational"  spam. 

■ SARE_BML_PRE25X  designed  to  catch  "business,  marketing  and  educational" 
spam. 

■ SARE_FRAUD  designed  to  catch  "Nigerian  419",  "International  Lotto",  etc.  type 
scams. 

■ SARE_FRAUD_PRE25X  designed  to  catch  "Nigerian  419",  "International  Lotto", 
etc.  type  scams. 

■ SARE_HEADER  contain  Pleader  rules  that  are  not  found  in  other  SARE 
rulesets. 

■ SARE_OEM  tries  to  detect  people  selling  OEM  software  to  consumers. 

■ SARE_RANDOM  tries  to  detect  common  mis-fires  on  bulk  mail  software.  Many 
signs  are  found  like:  %RND_NUMBER,  etc. 

■ SARE_SPECIFIC  ruleset  which  flags  specific  spam  and/or  spam  from  specific 
spammers. 
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■ SARE_SPOOF  tries  to  detect  common  spoofing  attempts  by  spammers.  Many 
use  a Message-ID  of  one  provider  but  the  message  was  never  passed  through 
the  suggested  system. 

■ TRIPWIRE  searches  for  3 characters  that  shouldn't  be  together.  This  is  based 
on  the  English  language. 

■ RANDOMVAL  lists  tags  spammers  sometimes  forget  to  convert  in  spam. 

■ SARE_EVILNUMBERS  lists  addresses  and  phone  numbers  harvested  from 
spam. 

■ SARE_GENLSUBJ  contains  Subject  header  rules  that  are  not  found  in  other 
SARE  rulesets. 

■ SARE_HIGHRISK  is  developed  because  there  are  spam  signs  which  readily 
detect  spam,  and  which  in  our  testing  do  not  flag  significant  ham,  but 
theoretically  there  is  no  reason  for  such  rules  not  to  flag  ham.  We  therefore 
consider  these  to  be  "high  risk"  rules,  useful  for  many  systems  at  this  time,  but 
not  suitable  for  systems  that  must  be  very  conservative  and  cautious  in  their 
spam  detection. 

■ SARE_HTML  contains  HTML  coding  rules  that  detect  various  spammer  tricks 
applied  through  HTML  coding  within  messages. 

■ SARE_OBFU  looks  for  obfuscation  within  emails.  It  looks  for  the  various  tricks 
spammers  use  to  hide  their  message  from  spam  filters,  while  keeping  their 
messages  readable  to  humans.  It  treats  these  as  spamsign. 

■ SARE_REDIRECT  detects  commonly  abused  redirectors  and  uri  obfuscation 
techniques. 

■ SARE_SPAMCOP_TOP200  contains  top  200  spam  relays  condensed  into  as 
few  rules  as  possible. 

■ SARE_STOCKS  contains  set  of  rules  for  stock  spams. 

■ SARE_UNSUB  looks  for  common  unsubscribe  phrases  and  codes  in  spam. 

■ SARE_URI  contains  files  look  for  spamsign  in  URI  links  within  emails.  It  is  not 
intended  to  replace  SURBL  or  BigEvil,  but  instead  will  use  characteritics  that 
these  domain-based  tests  cannot  track. 

■ SARE_WHITELIST  used  to  whitelist  newsletters  and  mailing  lists  that  are 
controlled/monitored  to  be  free  of  spam,  but  might  occasioanlly  be  flagged  as 
spam  by  SpamAssassin  because  of  "spammy"  contents. 

■ ZMI_GERMAN  contains  German  ruleset. 

■ MAIL_ADDRESS  - the  e-mail  address  where  SA  ruleset  update  notifications  will  be 

sent.  If  the  field  is  empty,  no  notifications  will  be  sent. 
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Migrating  Mail  Server/IP 

> To  move  the  mail  server  to  another  machine: 

1 Prepare  Servers 

1 . Prepare  a new  box  with  a mail  server  using  Parallels  H-Sphere  installer  as 
described  in  Parallels  H-Sphere  Adding  Servers  and  Services  Guide. 

2.  Create  a new  physical  server  and  add  a mail  server  group  (or  add  this  group  to 
the  physical  server  you  are  planning  to  move  mail  server  to). 

3.  Disable  signup  for  the  mail  server. 

2 Move  Mail  Content 

1 . As  the  cpanel  user  (on  page  65),  ssh  to  your  target  mail  server: 
ssh  rootQ<TARGET_MAIL_SERVER_IP> 

2.  Move  the  following  directories  from  the  source  to  the  target  mail  server: 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/ domains/ 
/hsphere/ local/var/ vpopmail /domains / 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/etc/ 

/hsphere/local/var/vpopmail/etc/ 

rsync  -arzgop  -e  ssh 

root@<SOURCE_MAIL_SERVERJP> : /var/qmail/control/ 

/ var/ qmail/ control/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /var/qmail/users/  /var/qmail/users/ 
rsync  -arzgop  -e  ssh  rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/horde/ 
~mysql/ horde/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/ spamassassin/ 

~mysql/ spamassassin/ 

3 Update  System  Database 

1 . Stop  the  Control  Panel  (on  page  54). 

2.  Log  into  the  Parallels  H-Sphere  system  database  (on  page  65)  and  run  the 
following  queries: 

update  l_server  set  p_server_id=<TARGET_PHYSICAL_SERVER_ID>  where 
id =<MAiL_LOGICAL_SERVER_ID> ; 

(1  record) 

update  l_server_ips  set  ip= ' <TARGET_MAIL_SERVER_IP> ' , 
mask= ' <TARGET_MAIL_SERVER_MASK>  ' where 
l_server_id=<MAIL_LOGICAL_SERVERJD>  and  flag=4; 

(1  record) 

3.  Start  the  Control  Panel  (on  page  54). 

4 Update  Reseller's  Server  Aliases 

As  the  cpanel  user,  run  the  following  java  tool: 
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java  psoft . hsphere . tools . ServerAliasesRenamer  --lserver 
<MAIL_LOGICAL_SERVER_ID> 

5 Mail  Content  Final  move 

1 . Stop  the  mail  and  mysql  service  (on  page  52)  on  the  source  server 

2.  As  the  cpanel  user  (on  page  65),  ssh  to  your  target  mail  server: 
ssh  rootQ<TARGET_MAIL_SERVER_IP> 

3.  Repeat  rsync  commands  from  Step  2 from  the  target  server 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/ domains/ 
/hsphere/ local/var/ vpopmail /domains / 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /hsphere/local/var/vpopmail/etc/ 

/hsphere/local/var/vpopmail/etc/ 

rsync  -arzgop  -e  ssh 

root@<SOURCE_MAIL_SERVER_IP> : /var/ qmail/ control/ 

/ var/ qmail/ control/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVER_IP> : /va.r/ qmail/users/  /var/qmail/users/ 
rsync  -arzgop  -e  ssh  rootQ<SOURCE_MAIL_SERVER_IP> : ~mysql/horde/ 
~mysql/ horde/ 
rsync  -arzgop  -e  ssh 

rootQ<SOURCE_MAIL_SERVERJP> : ~mysql/ spamassassin/ 

~mysql/ spamassassin/ 

4.  Start  the  mysql  service  (on  page  52)  if  you  have  a mysql  service  on  the  source 
box. 

6 Enable  Qmail  Forwarding  For  The  Time  of  DNS  Propagation 

The  possibility  to  use  POP3-before-SMTP  and  SMTP  AUTH  Authentication  for  the 
time  of  migration  has  been  implemented  since  mail2-all4  (/misc/mail2_all4.html).  If 
your  Parallels  H-Sphere  uses  an  older  mail  package,  please  skip  this  step. 

1 . Start  source  mail  server  with  the  "forward"  parameter: 

/etc/init .d/qmaild  forward 

When  prompted  "Enter  IP  address  of  the  destination  mail  server: ",  enter  the  IP  of 
the  target  physical  server.  This  IP  will  be  added  to  files 

/var/qmail/control/destip  and  /var/qmail/control/smtproutes 

and  will  be  used  for  further  server  restarts. 

2.  On  the  target  mail  server,  add  the  IP  of  the  source  server  as  an  IP  with  open 
relay. 

NOTE:  qmail  forward  switches  the  source  SMTP  server  into  relay  mode  and 
forwards  POP3  traffic  to  the  target  server  with  simultaneous  POP3-before- 
SMTP  authentication  on  the  source  box.  This  is  done  to  keep  using  the  old 
box  until  the  target  server's  DNS  settings  are  propagated  across  the 
Internet.  It  usually  takes  up  to  2 or  3 days.  After  that,  you  can  stop  the 
source  server. 

7 Change  the  A DNS  record  for  main  zone. 

Go  to  the  E-Manager  ->  DNS  Manager  and  delete  the  A DNS  record  with  the  old  IP  and 
add  it  with  the  new  IP. 
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8 Finish  off  the  migration 

1 . Check  if  you  have  -qmaiid/controi/outgoingip  file.  If  yes,  change  the  IP 
in  this  file  to  the  new  one. 

2.  Restart  qmail  service  (on  page  52)  on  the  target  box. 

3.  On  CP  server,  check  the 

~cpanel/ shiva/psoft  conf  ig/hsphere  .properties  file.  Here,  find  the 
SMTP_HOST  parameter.  If  it  is  set  to  the  old  mail  server  IP,  reset  it  to  the  new 
IP  or  to  the  SMTP  server's  hostname. 

4.  If  SMTP_HOST  parameter  was  changed,  restart  the  Control  Panel  (on  page  54). 

9 Check  mail  server  functionality. 
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Moving  Mail  Domains 

Moving  mail  domains  in  Parallels  H-Sphere  is  not  fully  automated,  which  means  it  can 
be  applied  to  individual  domains  or  small  groups  of  domains.  The  below  procedure 
doesn't  work  well  with  large  groups  of  mail  domains  or  entire  resellers. 

Please  be  prepared  that  due  to  the  propagation  of  the  new  IP  address,  mail  domain 
move  can  result  in  up  to  24  hour  downtime  and  inability  to  edit  the  mail  boxes. 

> To  move  a group  of  user  domains  from  one  mail  server  to  another: 

1 On  the  new  mail  server,  log  in  as  root  and  run  the  following 
commands  for  each  domian: 

1.  Register  a new  mail  domain: 

~vpopmail/bin/vadddomain  <DOMAIN_NAME>  <ANYPASS> 

2.  If  the  domain  you  are  moving  has  domain  aliases,  set  up  each  alias  by  the 
following  command: 

~vpopmail/bin/vaddaliasdomain  <DOMAIN_NAME>  <ALIAS_NAME> 

3.  Get  the  location  of  this  domain  directory: 

~vpopmail/bin/vdominfo  <DOMAIN_NAME> 

4.  Remove  the  content  of  this  directory: 
rm  -rf  <DOMAIN_DIRECTORY> 

5.  Copy  the  content  of  the  original  maildomain  directory  from  the  source  server: 

scp  -r  root$<OLD_SERVER_IP> : <SOURCE_DOMAIN_DIRECTORY> 
<DOMAIN_DIRECTORY> 

6.  Update  ownership  of  the  domain  directory  and  its  content: 
chown  -R  vpopmail : vchkpw  <DOMAIN_DIRECTORY> 
where: 

<DOMAIN_NAME>  is  the  mail  domain 

<ANYPASS>  is  any  string.  Later  it  will  be  replaced  with  the  real  password 
<DOMAIN_DIRECTORY>  is  the  location  of  the  domain  directory  on  the  target  server 
<SOURCE_DOMAIN_DIRECTORY>  is  the  location  of  the  domain  directory  on  the  source 
server 

<OLD_SERVER_IP>  is  the  IP  address  of  the  source  mail  server. 

7.  Restart  mail  server  (on  page  56)  to  apply  changes. 

2 If  the  domain  directory  path  is  different  on  the  source  and  target 
servers: 

1 . Go  to  the  domain  directory  on  the  target  server  and  update  all  mailbox  paths  in 
the  vpasswd  file  and  all  files  that  have  names  beginning  with  . qmaii- . 

2.  Add  and  delete  a temporary  mailbox  to  apply  changes: 
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[root@mail3  example . com] # ~vpopmail/bin/vadduser 
blala@example . com 

Please  enter  password  for  blala@example.com: 
enter  password  again: 

[root@mail3  example . com] # ~vpopmail/bin/vdeluser 
blala@example . com 

3 On  the  old  mail  server,  log  in  as  root  and  delete  the  domains  using 
this  command  for  each  domain: 

~vpopmail/bin/vdeldomain  <DOMAIN_NAME> 

4 Important!  Back  up  the  Parallels  H-Sphere  system  database. 

5 Log  into  the  system  database  (on  page  65)  and  run  the  following 
queries: 

1 . Set  new  logical  server  id  for  each  domain  name: 

UPDATE  mail_services  SET  mail_server=<NEW_LSERVER_ID>  WHERE 
id= (SELECT  child_id  FROM  parent_child  WHERE  child_type=1000 
AND  parent_id= (SELECT  id  FROM  domains  WHERE 
name= ' <DOMAIN_NAME> ' ) ) ; 

2.  Get  current  values  from  the  MX  and  CNAME  records  for  the  moved  domains: 

SELECT  r . id , r . name , r . type , r . data , r . ttl , r . pref  FROM 
domains  d,  parent_child  pi,  parent_child  p2 , dns_records  r 
WHERE  d . name= ' <DOMAIN_NAME> ' AND  d.id  = pl.parent_id  AND 
pi . child_type=1000  AND  pl.child_id  = p2.parent_id  AND 
p2 . child_id  = r . id  AND  (p2 . child_type=1007  OR 
p2 . child_type=3006) ; 

3.  Update  MX  and  CNAME  records  with  the  new  values: 

UPDATE  dns_re cords  SET  data= ' < TARGE T_MA I L_S E RVE R_NAME > ' WHERE 
id  in  (<MX_ID> , <CNAME_ID>) ; 

where  <MX_ID>  and  <CNAME_ID>  are  the  record  IDs  you  got  on  the  previous  step. 

4.  Restart  Parallels  H-Sphere  (on  page  54)  to  apply  changes. 

6 As  the  cpanel  user  (on  page  65),  update  your  DNS  settings  using  the 
DNS  Creator  utility: 

java  psoft . hsphere . tools . DNSCreator  -m  db  -dz  -z  <DOMAIN_NAME> 
where  <DOMAIN_NAME>  is  the  domain  name  you  are  updating  MX  and  CNAME  for. 
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Calculating  Mail  Traffic 

This  document  explains  how  Parallels  H-Sphere  collects  and  rotates  mail  traffic. 

Parallels  H-Sphere  cron  script  (on  page  33)  responsible  for  analyzing  mail  traffic  is 

/hsphere/ shared/ scripts/ cron/mail  anlz  . sh.  The  script  runs  daily, 
processes  the  qmail  traffic  log  file  (on  page  33)  and  collects  mail  statistics  into  the 
specially  formatted  dd.mm.YYYY.qmi.txt  log  files  in  the  Parallels  H-Sphere  statistics 
directory  /hsphere/ local /var/ statistic.  Here,  dd .mm.  yyyy  is  current  date 
timestamp. 

dd . mm . yyyy  . qmi . txt  log  files  contain  lines  of  the  following  format: 

| name | xFer ( kB) | Hits_All | Hits_HTML | 

where  name  is  the  domain  name,  xFer  is  the  total  traffic  in  kilobytes. 

Then,  Parallels  H-Sphere  TrafficLoader  utility  is  launched  by  cron  to  collect  mail  traffic 
from  the  statistics  directory  and  to  store  it  into  the  system  database.  TrafficLoader  also 
calls  the  /hsphere/ shared/ scripts/xf er_cat . pi  script  to  move  the  already 
loaded  mail  statistics  files  to  the  /hsphere /local /var/ statistic/ loaded 

directory  as  dd . mm . yyyy  . qmi . txt . gz  archives. 

In  this  section: 
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Mail  Traffic  Log 

qmail  writes  a detailed  mail  traffic  log  to  the  /var/hsphere/maii/iogs/stats  file. 
To  view  detailed  descriptive  mail  statistics  from  this  file,  run: 

/var/qmail/bin/mailstatistics  -v  -f  /var/hsphere/mail/logs/stats 

The  -v  option  provides  a verbose  mode. 


Log  records  in  the  file  have  the  following  format: 

date  host  msg_type [pid] : 

timestamp | sender | recipient | bytes | status | attempts 

Here: 

■ date : date  where  the  message  is  sent  or  received,  e.g.,  "Jun  20  18:20:14" 

■ host:  mail  server  host,  e.g.,  "mail.example.com" 

■ msg_type:  in  for  incoming  thread,  and  out  for  outgoing  thread 

■ pid:  PID  of  the  process 
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■ timestamp : UNIX  timestamp  (in  seconds  since  1 Jan  1970)  of  the  date  when  the 
message  is  sent,  e.g.,  1 1 1 928081 4 

■ sender:  message  sender's  e-mail  address 

■ recipient:  message  recipient's  e-mail  address.  For  multiple  recipients  each  one  a 
separate  line  in  the  log 

■ bytes:  message  size 

■ status:  message  status.  It  is  different  for  incoming  and  outgoing  mail 
Incoming  mail: 

■ success  - message  is  received  successfully 

■ timeout  - no  response  from  the  source  host  while  receiving  the  message 

■ rejclam  - message  is  received  completely  but  detected  as  infected  when  the 
proper  mail  resource  is  configured  to  remove  virused  message 

■ rejspam  - message  is  received  completely  but  detected  as  spam  when:  (1)  the 
proper  mail  resource  is  configured  to  remove  spam  message  or  (2)  when  the 
score  of  the  spam  message  exceeds  the  MaxScore  parameter 

■ manyhops  - message  is  looping 

■ mboxoverquota  - over  quota 

■ badmime  - used  bad  mime  type  of  the  mail  message 
bytestooverflow - message  exceeds  size  limit  Outgoing  mail: 

■ success  - message  is  sent  successfully 

■ timeout  - no  response  from  destination  host  while  sending  the  message 

■ partial  - malformed  incoming  message 

■ readerr-  internal  server  problems 

attempts:  number  of  data  transfers  per  one  SMTP  session  Example: 

tail  -f  /var/hsphere/mail/logs/stats 

Jun  20  18:20:14  mail.example.com  in[16723]: 

1119280814 | test@ yahoo . com | postmasters test . com | 69 | success 
Jun  20  18:20:14  mail.example.com  in[16723]: 

1119280814 | test 8 yahoo . com | tests test . com | 69 | success 
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POP3  and  IMAP  Traffic 

To  view  detailed  descriptive  IMAP  statistics,  run: 

cat  /var/hsphere/mail/logs/stats | grep  -i  imap 

POP3  statistics: 

cat  /var/hsphere/mail/logs/stats | grep  -i  pop3 

POP3  and  IMAP  traffic  have  the  same  format  as  Qmail  traffic  (on  page  116),  except  the 
e-mail  addresses  there  look  like  imap@<accounf>  for  POP3  and  pop3@<accoi/nf>  for 
POP3. 


Web  Mailing  List  Traffic 

To  view  detailed  descriptive  web  mailing  list  statistics,  run: 

cat  /var/hsphere/mail/logs/stats  | grep  maillist 

Web  mailing  list  traffic  has  the  same  format  as  Qmail  traffic,  except  that  in  sender  field 
it  includes  'web@maiiiist'  to  identify  its  type. 


SpamGuard  Setup 

> To  set  up  SpamGuard: 

1 Download  SpamGuard:  http://www.enderunix.org/spamquard/ 

2 Execute  tar  xfz  spamguard-x . x . tar . gz 

3 Go  to  / root/inst/ spamguard-x . x/ 

4 Read  the  INSTALL  and  README  files 

5 Install  SpamGuard  following  the  instructions  in  the  INSTALL  and 
README  files 


IMPORTANT:  You  must  put  all  your  system  domain  names  to  the  Spamguard's  ignore 
list  to  avoid  any  casual  chance  of  their  appearance  in  the  blacklist! 

Please  follow  instructions  in  the  POST-INSTALL  file. 

Warning:  For  the  time  being,  there  is  no  effective  way  of  combining  mailing  lists  and 
spamguard  protection.  You  need  to  configure  spamguard  manually  by  setting  the 
maximum  allowed  number  of  recipients. 
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Parallels  H-Sphere  DNS  service  can  use  either  MyDNS  (on  page  203)  or  the  bind8.x, 
9.x  package.  If  you  use  the  Linux  RedHat  autoupdates,  be  careful  not  to  update  bind. 

To  disallow  user  zones  on  a particular  DNS  server,  disable  user  signup  for  this  logical 
server  through  Parallels  H-Sphere  web  interface.  This  way,  old  customers  will  keep 
using  it,  and  new  customers  won't. 

Resellers  can  run  on  dedicated  and  shared  IPs.  You  can  disable  dedicated  IP  hosting 
for  resellers.  Read  how  to  configure  DNS  for  resellers  in  Parallels  H-Sphere  Service 
Administrator  Guide. 

Parallels  H-Sphere  does  not  provide  support  for  Reverse  DNS. 
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DNS  Config  Files 

The  main  configuration  file  location  is  /etc/named,  conf 
It  contains  the  following  data: 

options  { 

directory  "/hsphere/local/var/ named" ; 
listen-on  { 127.0.0.1; 

YOUR_IP_l ; 

YOUR_IP_2 ; 

YOUR_IP_N;  } ; 
notify- source  ; 

pid-f ile  " /hsphere/local/var/ named/ named . pid" ; 

} ; 

zone  IN  { type  hint;  file  " local/named . ca" ; }; 

zone  "localhost"  IN  { type  master;  file  "local/localhost . zone" ; allow- 
update 

{ none;  };  }; 

zone  "0 . 0 . 127 . in-addr . arpa"  IN  { type  master;  file  "local/named . local" ; 
allow-update  { none;  };  }; 

include  "zones^index.conf"; 
acl  anyip{any;}; 


Parallels  H-Sphere  DNS  Zones 

The  main  named  directory  both  on  master  and  slave  DNS  servers  is 

/hsphere/local/var/ named/. 

It  Contains  the  zones  index  . conf  file,  the  zones  (NUMBER)  . conf  files  and  the 
zones  (NUMBER)  directories,  where  (NUMBER)  =1,2,...,  22 
This  structure  contains  Parallels  H-Sphere  DNS  info  and  files.  To  find  a zone,  execute 
the  following  commands: 

# cd  /hsphere/local/var/named/ 

# grep  "Zone.Name.com"  * .conf 

It  will  return  the  data  which  contains  the  zone  file  location.  But  please  do  not  modify  it 
manually,  especially,  if  you  do  not  understand  what  you  do. 

The  localhost  and  0.0.127.  in-addr . arpa  zones  files  are  located  in  the 

/hsphere/local/var/ named/ local/  directory. 

Custom  DNS  Zones 

If  you  need  to  add  a custom  zone,  we  recommend  placing  it  into  this  directory.  Note 
that  Parallels  H-Sphere  won't  manage  your  custom  zones,  you  will  have  to  manage 
them  manually. 
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Reverse  DNS 

Parallels  H-Sphere  does  not  manage  reverse  DNS.  To  configure  reverse  DNS  globally 
for  the  main  Parallels  H-Sphere  domain,  Parallels  H-Sphere  owner's  ISP  or  domain 
registration  company  should  accordingly  configure  reverse  DNS  for  this  domain  on  their 
DNS  servers. 


Restarting  Named 

> To  start,  stop,  or  restart  named  on  the  Parallels  H-Sphere  DNS  server: 

1 Log  in  as  root. 

2 Run  the  respective  command  below. 

Warning:  Do  not  use  kill  -9  to  stop  named,  as  it  may  cause  information  loss!!! 

Linux: 

Starting:  / etc/ rc . d/ init . d/ named  start 
Stopping:  /etc/rc  . d/init . d/named  stop 
restarting:  /etc/rc.  d/init.  d/named  restart 

FreeBSD: 

For  Bind  9.3  and  up  (on  page  198): 

Starting:  /usr/local/etc/rc.  d/named,  sh  start 
Stopping:  /usr/local/etc/rc  . d/named,  sh  stop 
restarting:  /usr/local/etc/rc.  d/named.sh  restart 

For  Bind  8.x: 

Starting:  /usr/sbin/named  -u  named 
Stopping:  /usr/sbin/ndc  stop  -u  named 
restarting:  /usr/sbin/ndc  restart  -u  named 

Warning:  Without  "-u  named",  the  command  will  run  under  root. 

Usually,  a Parallels  Pi-Sphere  DNS  server  contains  a cron  DNS  check  which  starts 
every  1 or  2 minutes  and,  if  named  is  not  started,  starts  it.  Therefore,  do  not  feel 
alarmed  if  you  stop  named  and  see  that  it  keeps  working  for  another  several  minutes. 
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This  section  outlines  some  peculiarities  of  Bind  9.3  in  comparison  with  Bind  8.x. 


In  this  section: 


New  Features 199 

Restarting  Bind 199 

Using  rndc 200 


New  Features 

■ Bind  9.3  is  started/stopped/restarted  via  hsphere-daemontools-0.76-1 , the  package 
built  on  the  basis  of  DJB  daemontools  (http://cr.yp.to/daemontools.html).  This 
package  is  included  into  Parallels  H-Sphere  installation  and  is  used  with  the 
Parallels  H-Sphere  mail  service  (on  page  149)  package. 

■ The  named  daemon  is  administered  by  the  rndc  utility,  not  by  ndc. 

■ ndc  restart  is  no  longer  supported. 


Restarting  Bind 

Since  Bind  9.3,  the  Daemon  Tools'  svc  utility  is  called  in  the  named  daemon  to  stop, 
start  and  restart. 

The  procedure  of  stopping/starting/restarting  named  (on  page  57)  remains  the  same. 
However,  you  may  use  Bind  stop/start/restart  using  svc  as  an  alternative: 

Enter  the  /service  directory: 

cd  /service 

This  directory  is  used  by  daemontools  and  contains  symlinks  to  standard  service 
directories. 

> To  stop  Bind,  run: 

/command/ svc  -kd  named 

> To  start  Bind,  run: 

/command/svc  -u  named 

This  sequence  is  equivalent  to  restarting  named. 
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Using  rndc 

Bind  includes  a utility  called  rndc  which  allows  you  to  use  command  line  statements  to 
administer  the  named  daemon,  locally,  or  remotely. 

Managing  DNS  Zones 

> To  reload  a DNS  zone: 

rndc  reload  <ZONE> 

> To  reload  all  DNS  zones: 

rndc  reload 

After  that,  only  changed  zones  will  be  reloaded. 

> To  suspend  updates  to  a dynamic  zone: 

rndc  freeze  <ZONE> 

> To  enable  updates  to  a frozen  dynamic  zone  and  reload  it: 

rndc  thaw  <ZONE> 

Run  rndc  for  more  options. 

rndc  Config  File 

/etc/rndc . conf 

If  rndc  is  unable  to  connect  to  named,  check  the  /etc/rndc . conf  and 
/etc/named,  conf . For  details  on  rndc  configuration,  run: 

rndc- conf gen 


WARNING:  It  is  strongly  unrecommended  to  manually  edit  the  configuration  files,  as  it 
may  lead  to  misconfiguration  in  dynamic  zone  updates!  Please  also  read  how  to 
customize  config  file  for  DNS  from  Appendix  C of  Parallels  H-Sphere  Installation  Guide. 
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Adding  DNS  Servers 

There  are  two  possible  options  to  set  up  DNS  servers: 

■ put  each  named  to  separate  boxes 

■ put  all  DNS  servers  to  one  box 

Note:  The  latter  option  requires  the  so-called  single  DNS  configuration.  For  more 
details,  click  here  (on  page  201). 


> To  add  Parallels  H-Sphere  DNS  server  to  a new  physical  box: 

1 Prepare  the  box  for  DNS  service  installation  according  to  the 
instructions  from  Parallels  H-Sphere  Installation  Guide. 

2 Download  and  run  the  installation  script  according  to  the  Adding 
Servers  and  Services  Guide. 

If  you  need  to  add  a DNS  server  to  a live  Parallels  H-Sphere  physical  server,  follow  the 
instruction  on  adding  services. 


Configuring  Single  DNS 

Single  DNS  configuration  enables  to  allocate  two  or  more  DNS  servers  on  one  physical 
box.  In  this  mode,  Parallels  H-Sphere  emulates  full-featured  DNS  configuration  where 
each  DNS  server  has  its  own  bound  IP.  This  allows  customers  with  a single  box 
installation  to  use  services,  such  as  OpenSRS  domain  registration,  that  require  at  least 
two  DNS  servers. 


WARNING:  Single  DNS  mode  is  available  only  if  all  DNS  servers  are  configured 
on  one  physical  box!  You  cannot  have  two  DNS  logical  servers  on  one  box  if  you 
have  another  DNS  server  on  a separate  box. 


To  put  an  extra  DNS  server  to  single  DNS  configuration: 

1 Add  another  DNS  logical  server  to  the  physical  server  with  DNS  via 
the  interface  as  described  in  Parallels  H-Sphere  Service  Administrator 
Guide. 

2 Log  in  as  cpanel  user  and  run  the  following  java  tools: 

■ ClusterPreparer: 

su  - cpanel  -c  "java  psoft.hsinst .boxes .ClusterPreparer" 

■ DNSCreator: 

su  - cpanel  -c  "java  psoft . hsphere . tools . DNSCreator  -m  rand" 
Read  more  about  DNSCreator  options  (on  page  211). 

3 Execute: 
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/hsphere/ local/ conf ig/bind/ scripts/ conf ig_bind 

4 Restart  named  service. 
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Installing  and  Configuring  MyDNS 

MyDNS  is  a DNS  server  for  UNIX  that  serves  records  directly  from  an  SQL  database 
and  can  be  used  in  Parallels  H-Sphere  as  an  alternative  to  bind  (on  page  196). 
Currently  Parallels  H-Sphere  supports  MyDNS  to  work  only  with  MySQL. 

Installation 

> To  configure  Parallels  H-Sphere  to  work  with  MyDNS: 

1 Download  the  latest  version  of  MyDNS  from  http://mydns.bboy.net. 

2 Install  and  configure  MyDNS  version  that  is  served  by  MySQL  DB  on  a 
new  or  any  of  your  existing  Parallels  H-Sphere  servers  following  the 
MyDNS  installation  instructions 

(http://mydns.bbov.net/doc/html/mydns  2.html#SEC2). 

You  can  either  install  MyDNS  .rpm  package  or  compile  it. 

Warning:  Do  not  rename  the  'mydns'  MySQL  DB  created  during  the  installation. 

3 Add  the  following  lines  into  the 

~cpanel / shiva/  psof  t_conf  ig/h  sphere  . properties  file: 

MYDNS_USER  = <login> 

MYDNS_PASS  = <password> 

MYDNS_DB_HOST  = <IP> 

Where: 

■ login  is  the  MySQL  user  name  to  access  MyDNS  MySQL  DB  with 
select/insert/update/delete  privileges.  You  will  need  to  create  one  more  MySQL 
user  than  is  described  in  MyDNS  installation  instructions  and  GRANT  ALL 
privileges 

■ password  is  the  password  for  MyDNS  user  login 

■ IP  is  the  IP  of  the  server  with  MySQL  DB  created  during  the  installation 

4 In  the  admin  control  panel  check  if  MyDNS  name  server  is  listed  as  a 
server  group.  If  it's  not,  log  into  the  system  database  (on  page  65)  and 
execute: 

INSERT  INTO  l_server_groups  (id,  type_id,  name)  VALUES  (21,  2, 
'MyDNS  name  server' ) ; 

5 Restart  your  CP  (on  page  54). 

6 If  you  install  MyDNS  on  a new  server,  add  this  physical  server  as 
described  in  Parallels  H-Sphere  Service  Administrator  Guide. 

7 Add  MyDNS  logical  server(s)  via  the  interface  with  the  MyDNS  name 
server  group  and  check  if  it  is  available  for  signup. 
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Uninstallation 

To  remove  Parallels  H-Sphere  DNS  service,  remove  the  'hsphere-bind'  package  by 
running: 

rpm  -e  hsphere-bind-XXX 


Note:  After  running  this  command,  commands  like  host,  dig,  nslookup  and  others  may 
disappear. 

Therefore,  it  is  recommended  that  afterwards  you  install  additional  packages:  bind- 
libs-XXX. rpm  and  bind-utils-XXX . rpm. 


Migrating  DNS  from  Bind  to  MyDNS 

> To  migrate  DNS  from  BIND  to  MyDNS: 

1 Execute  stepsl-3  of  Installing  and  Configuring  MyDNS  (on  page  203). 
MyDNS  front  end  servers  must  be  installed  on  the  servers  where  you 
have  got  Parallels  H-Sphere  BIND  name  servers  installed. 

2 Restart  CP  (on  page  54) 

3 Log  to  CP  server  as  the  cpanel  user  (on  page  65) 

4 To  transfer  DNS  zones  and  records  to  MyDNS,  run: 

java  psoft . hsphere . tools .MigratorToMyDNS  [-dz | --delete_zones] 

If  you  specify  -dz  or  — deiete_zones  option,  then  the  utility  will  try  to  delete  each 
DNS  zone  on  the  new  set  of  DNS  logical  servers  before  recreating  them. 

5 Restart  CP  (on  page  54). 

6 Stop  Bind. 

7 Add  external  DNS  server  to  /etc/resolv.conf  as  described  in  Appendix 
C.  Customizing  Configuration  Files  of  Parallels  H-Sphere  Installation 
Guide  for  each  MyDNS  server. 
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Moving  DNS 

DNS  servers  can  be  moved  only  to  Linux/Unix  boxes.  You  can't  move  DNS  to  a 
Windows  platform. 

1 Prepare  a new  box  with  DNS  using  Parallels  H-Sphere  installer. 

2 Using  E.Manager,  create  a new  physical  server  and  add  the  DNS  server 
group  (or  add  this  group  to  the  physical  server  you  are  planing  to 
move  DNS  server  to). 

3 Stop  the  Control  Panel  (on  page  54). 

4 Log  into  the  system  database  (on  page  65)  and  run  the  following  DB 
queries: 

update  1 server  set  p server  id=[new_p  server  id]  where 
id=[id  of  DNS  logical  server] ; 

update  1 server  ips  set  ip= ' [new  DNS  server  IP] 
mask=' [new  DNS  server  mask] ' where 

1 server  id=[id  of  DNS  logical  server]  and  flag=4; 
select  * from  1 server  ips  where 

1 server  id=[id  of  DNS  logical  server]  and  flag  in  (5,6); 

5 Move  all  IPs  selected  from  Parallels  H-Sphere  database  (with  flags  5 
and  6)  to  the  new  server.  This  means  that  you  need  to  remove  these 
IPs  from  the  network  interface  on  the  old  DNS  server, 

/etc/named,  conf  ("Listen  on"  directive)  and 

/hsphere/ local/ network/ ips  files,  and  set  them  on  new  server 
(on  network  interface,  /etc/named . conf  and 
/hsphere / local/ network  / ips  files). 

6 Perform  this  step  ONLY  if  you  are  running  two  DNS  servers  on  one 
box  and  are  separating  them.  This  must  be  done  on  the  source  server. 
Go  to  the  directory  /hsphere/shared/scripts/MultiDNS/  and  copy  its 
contents  one  level  higher  overwriting  the  target  files: 

# cd  /hsphere/shared/scripts/MultiDNS/ 

# cp  . /*  . . / 

7 Move  DNS  data.  You  can  choose  between  two  possibilities:  physical 
move  or  recreation  of  DNS  zones. 

■ Physical  move: 

1 . Move  the  /hsphere/local/var/named  directory  from  old  DNS  server  to  the  new 
server. 

2.  Change  the  ownership  of  moved  files  to  namedmamed: 
chown  -R  named: named  /hsphere/local/var/named 

3.  On  the  rest  of  DNS  servers,  for  slave  zones  which  had  masters  set  to  the  old 
DNS  server  IP,  change  it  to  the  new  DNS  server  IP  (using  SED  or  any  other 
method). 

4.  Restart  named  (on  page  57). 
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■ DNS  recreation  tool: 

1 . Log  into  your  CP  server  as  the  cpanel  user  (on  page  65). 

2.  Execute  the  following  command  (it  may  take  a while  if  you  have  many  DNS 
zones): 

java  psoft.hsphere. tools. DNSCreator  -m  db  -dz 

8 Start  the  Control  Panel  (on  page  54). 

9 Change  the  IP  in  A DNS  record  for  the  DNS  server  in  the  service  DNS 
zone  (using  the  Control  Panel). 
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Removing  Broken  DNS  Zones 

This  document  contains  step-by-step  instruction  on  how  to  remove  the  DNS  zone  if, 
while  adding  DNS  zone  for  a domain,  the  following  error  message  shows  up: 

Zone  ...  has  been  taken 

See  also  the  troubleshooter 

(http://hsphere.parallels.com/HSdocumentation/FAQ/troubleshooter.php). 

Note:  Here,  we  deal  with  such  issues  where,  by  some  reason,  DNS  zone  was  not 
correctly  created  or  not  completely  removed  from  the  system.  We  do  not  consider 
cases  where  this  DNS  zone  exists  on  a live  account. 

First  of  all,  you  need  to  check  from  the  CP  interface  if  this  domain  zone  is  indeed 
removed.  For  this,  choose  the  Search/In  resellers  menu  and  search  for  the  domain  name. 

If  no  account  is  found,  you  need  to  remove  the  DNS  zone  from  the  Parallels  H-Sphere 
database. 

1 We  strongly  recommend  you  to  back  the  database  up  before  you  make  changes  in 
it. 

2 Use  transactions  when  you  modify  tables.  Transactions  have  the  following  format: 

begin;  - start  the  transaction,  [statements  for  modifying  data:  delete,  insert, 
update,  and  the  like] 

rollback;  - rollback  the  transaction;  also  perform  rollback  when  you  make  a 
syntax  error  in  the  previous  statement. 

commit;  - commit  the  transaction. 

Use  either  rollback;  or  commit;  to  finish  the  transaction. 

The  following  tables  and  fields  are  considered  in  this  guide: 

■ dns_zones  - the  list  of  DNS  zones. 

dns_zones . id  - DNS  zone  resource  identifier; 
dns_zones  .name  - DNS  zone  domain  name. 

■ parent_chiid  - the  tree  of  resources  related  to  accounts.  Account  is  a root 
resource.  Certain  account  resources  (parent  resources)  may  have  child  resources. 

parent_child.  account_id=accounts  . id  - account  identifier; 

parent_chiid. parent_id  - parent  resource  identifier; 

parent_chiid.  chiid_id  - child  resource  identifier.  DNS  zone  is  a child 
resource  to  the  account. 

■ accounts  - the  list  of  accounts, 
accounts . id  - account  identifier; 
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account . deleted  - contains  the  date  when  the  account  has  been  deleted,  or 
NULL  if  the  account  is  alive; 

■ users  - the  list  of  end  users, 
users . id  - user  id; 

users . reseller  id=reseiiers . id  - id  of  the  reseller  under  whom  this  user  is 
created;  1 if  the  user  has  no  reseller. 

■ user_account  - the  table  which  maintains  the  user-account  correspondence.  It 
links  the  users  and  accounts  tables. 

user_account . user_id=users  . id  - user  id; 

user_account . account_id=accounts  . id  - account  id  for  this  user. 

■ resellers  - the  list  of  resellers, 
resellers  . id  - reseller  id. 

■ e_zones  - the  list  of  service  DNS  zones. 

e zones.  id=dns  zones  . id  - service  DNS  zone  id; 

e zones  . reseller  id=resellers  . id  - id  of  the  reseller  who  hosts  this  zone. 

1 Check  if  the  DNS  zone  is  present  in  the  database: 

select  * from  dns_zones  where  name  = 'domain.com'; 

Here,  domain . com  is  the  DNS  zone  name. 

2 Find  out  the  type  of  the  DNS  zone  (user  DNS  zone  or  service  DNS 
zone). 

select  account_id  from  parent_child  where  child_id  = 
<dns_zone_id> ; 

If  the  query  returns  nothing,  the  DNS  zone  is  the  service  DNS  zone. 

Otherwise,  it  is  the  user  DNS  zone.  parent_chiid.  account_id  is  the  account 
under  which  this  DNS  zone  is  created. 

In  this  section: 
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Removing  User  Domain  Zone 

1 Check  if  the  account  for  the  DNS  zone  is  deleted: 

select  deleted  from  accounts  where  id  = <account_id>; 

2 If  accounts  . deleted  is  not  null,  it  means  that  the  account  has 
been  deleted. 

In  this  case,  it  is  required  to  remove  all  records  with  this  account  id  from  the 

parent_child  table: 

begin; 

delete  from  parent  child  where  account  id  = <account  id>  and 

account  id  <>  child  id; 

commit; 

3 If  account . deleted  is  null,  check  if  there  is  a user  for  this 
account: 

select  * from  user_account  where  account_id  = <account_id>; 

If  this  query  returns  nothing,  we  have  got  an  error:  account  exists,  but  no  user 
corresponds  to  this  account.  In  this  case,  you  should  run  the  DeietedAccounts 
Java  utility: 

1 . Log  into  your  control  panel  server  as  cpanel  user  running  the  following 
command: 

su  -1  cpanel 

2.  Execute  the  following  command: 

java  psof t . hsphere . tools . DeleteAccounts 

Then,  enter  the  ids  of  the  accounts  you  wish  to  delete,  or  create  the  file  with  these 
account  ids  in  separate  lines  and  redirect  it  to  the  standard  input  of  the  above 
command: 

3.  Make  sure  you  are  logged  as  cpanel  user. 

4.  Execute  the  following  command: 

java  psof t. hsphere . tools . DeleteAccounts  < 
f ile_wi th_account_ids 

Note:  DeleteAccounts  should  not  be  used  against  reseller  accounts! 
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Removing  Service  Domain  Zone 

1 Find  the  reseller  id  for  this  DNS  zone: 

select  reseller_id  from  e_zones  where  id  = <dns_zone_id>; 

2 Find  the  reseller  in  the  resellers  and  users  table: 

select  * from  resellers  where  id  = Creseller  id>; 
select*  from  users  where  id  = Creseller  id>; 

3 If  the  reseller  is  not  found  in  any  of  these  tables: 

1 . Change  the  reseller  id  to  1 in  the  e_zones  table: 
begin; 

update  e zones  set  reseller  id  = 1 where  id  = <dns  zones  id>; 
commit; 

2.  Restart  CP. 

3.  Remove  the  DNS  zone  from  the  CP  admin  interface  in  the  E. Manager/DNS  Settings 
menu. 
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Using  DNS  Creator 

DNS  Creator  is  a utility  that  re-creates  DNS  data  to  new  DNS  servers.  Use  this  utility  to 
republish  DNS  data  to  a different  box  or  add  an  extra  DNS  server. 

> To  create  DNS: 

1 Log  into  your  control  panel  server  as  the  cpanel  user  (on  page  65). 

2 Run  DNS  Creator: 

java  psoft . hsphere . tools . DNSCreator  -m  creation_method  [-dz] 
[-z  zone name ] 

-m  creation  method.  Possible  values:  db  or  rand 

■ db  - pick  NS  servers  as  they  are  defined  in  the  Parallels  H-Sphere  database 

■ rand  - pick  NS  servers  randomly 

-dz  | — deiete_zones  - delete  zones  first.  Add  this  option  only  if  such  zones 
already  exist.  With  this  option,  DNS  creation  will  take  at  least  twice  more  time. 

-lids  | --logical-servers  - process  zones  which  are  on  the  logical  servers 
with  the  specified  IDs. 

-pip  | — pServeriP  - specifies  a physical  server  by  its  primary  IP.  All  necessary 
logical  server  IDs  are  chosen  automatically.  Often  -p/p  is  used  as  an  alternative  to  - 
lids. 

-z  | — zone  - recreate  only  one  specified  zone.  Without  this  option,  all  zones  will 
be  recreated. 

Note:  If  both  lids  and  -z  parameters  are  specified,  the  -z  parameter  will  be 
ignored. 


Note:  If  you  are  adding  an  extra  DNS  server,  specify  -m  rand  or  else  this  new  DNS 
server  will  be  available  only  for  new  signups. 


Please  be  patient.  If  you  have  hundreds  of  domains,  this  utility  might  take  hours  to  have 
executed. 
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MySQL  Server 


This  chapter  describes  some  task  you  may  need  to  perform  on  your  Parallels  H-Sphere 
MySQL  server. 

MySQL  server  log  file  is/var/iog/mysqid. 

MySQL  comes  with  PhpMyAdmin  (http://www.phpmyadmin.net/)  which  is  a MySQL 
administration  Web  interface  written  in  PHP.  It  is  installed  as  an  hsphere- 
phpmyadmin -<version>-<build>  package,  where  <version>  is  PhpMyAdmin  version,  and 
<build>  is  this  package's  build  number. 

PhpMyAdmin  installation  directory  is 

/hsphere/ shared/ apache/htdocs /phpMyAdmin. 


In  this  chapter: 

Installing  MySQL  Server 212 

Backing  Up  MySQL  Database 214 

Running  Parallels  H-Sphere  MySQL  Scripts 215 

Getting  Remote  Access  to  MySQL  Logical  Server 216 

Enabling  Linked  Tables  in  phpMyAdmin 217 

Changing  MySQL  Root  Password 218 

Moving  MySQL 220 

Moving  MySQL  Accounts 222 


Installing  MySQL  Server 

Below  is  the  procedure  of  installing  MySQL  database  software  and  adding  MySQL 
server  to  Parallels  H-Sphere  cluster. 

In  this  section: 

Step  1.  Checking  for  MySQL  on  Your  Box 213 

Step  2.  Downloading  MySQL 213 

Step  3.  Installing  MySQL 213 

Step  4.  Configuring  MySQL 214 

Step  5.  Adding  MySQL  Server  to  Parallels  H-Sphere 214 
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Step  1 . Checking  for  MySQL  on  Your  Box 

First,  check  whether  MySQL  database  server  is  installed.  You  can  do  this  by  entering 
the  following  command  into  your  command  prompt: 

which  mysql 

If  it  returns  you  a path,  for  example  "/usr/bin/mysqi",  you  have  MySQL  database 
software  installed.  Alternatively,  you  can  try  to  find  an  installation  of  MySQL  by  running 
the  following  command  in  your  command  prompt: 

rpm  -qa  | grep  -i  mysql 

If  this  gives  you  something  like: 

mysql-4 .0.16-0 
mysql -client- 4 .0.16-0 

you  already  have  MySQL  DBMS  installed. 


Step  2.  Downloading  MySQL 

If  you  do  not  have  MySQL  installed,  download  MySQL  binary  RPM  distribution.  On  the 
Web  site  www.mvsgl.com,  go  to  the  Download  section,  select  the  latest  stable  release, 
than  select  "The  server  for  i386  systems"  from  the  "Standard  binary  RPMs"  list.  Also,  you  will 
need  client  programs,  so  go  back  to  the  Download  section  and  download  "client  programs 
for  i386  systems"  from  the  "Standard  binary  RPMs"  list. 

Step  3.  Installing  MySQL 

Now  that  you  have  downloaded  MySQL  database  software  installation  package, 
execute  the  following  command: 

rpm  -ivh  /path/to/downloaded/mysql-4 . xx . xx-x . rpm 

where  mysql-4 . xx . xx-x . rpm  is  MySQL  binary  RPM  distribution  filename. 
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Step  4.  Configuring  MySQL 

To  get  MySQL  working,  you  now  need  to  configure  the  software  installed. 

Connection  from  Parallels  H-Sphere  to  MySQL  database  is  performed  via  SSH.  In 
order  to  connect  to  MySQL  database  with  a user  name  and  password,  put  the 
. my . cnf  file  in  the  home  directory  of  the  user  under  which  SSH  connection  is 
established.  Typically,  it  is  the  mysqi  user.  To  find  out  the  path  to  the  MySQL  home 
directory,  log  in  as  the  mysqi  user  under  root,  and  then  type  pwd: 

# su  - mysqi 

# pwd 

Or,  finger  the  mysqi  user  for  details: 

# finger  mysqi 

In  .my.  cnf,  you  must  insert  the  following  lines: 

[client] 

user=login  of  some  highly_privileged  user 
password=his_pas sword 

where  login  of  some  highly  privileged  user  is  the  login  name  of  MySQL 
database  user  which  have  insert,  update,  delete,  select,  privileges  on  MySQL  system 
database  (those  called  mysqi).  hi s_pas sword  is  the  plain  text  password  of  this  user. 


WARNING:  For  security  reasons,  you  MUST  set  access  type  for  . my . cnf  file  to  0400 
or  0600. 


Step  5.  Adding  MySQL  Server  to  Parallels  H-Sphere 

After  you  have  installed  and  configured  MySQL  software  on  a new  box,  add  MySQL 
server  to  Parallels  H-Sphere  cluster  as  described  in  Adding  Servers  and  Services 
Guide.  If  MySQL  is  installed  on  a live  Parallels  H-Sphere  box,  add  MySQL  as  a new 
Parallels  H-Sphere  service. 


Backing  Up  MySQL  Database 

To  back  up  MySQL  database,  back  up  the  MySQL  home  directory,  or  use  the 
mysqidump  utility  to  dump  the  database.  Type  'man  mysqi',  'man  mysqidump'  or  see 
MySQL  documentation  (http://www.mvsql.com/documentation/)  for  details. 
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Running  Parallels  H-Sphere  MySQL 
Scripts 

On  the  MySQL  database  box  the  following  scripts  are  installed  in 

/hsphere/ shared/ scripts: 

mysql-change-user-password  - Changes  user  password 
mysql-change-user-password.  sh  - changes  user  password 
mysqi-db-size  - calculates  database  size 
mysqi-db-size  .pi  - calculates  database  size 
mysql-drop-database  - drops  database 
mysql-drop-database  . sh  - drops  database 
mysqi-resume-user  - resumes  suspended  user 
mysqi-resume-user . sh  - resumes  suspended  user 
mysqi-create-db  - creates  database 
mysqi-create-db . sh  - creates  database 

mysqi-db-users  - lists  MySQL  database  users  who  have  any  privilege  on  this 
database 

mysqi-db-users . sh  - lists  MySQL  database  users  who  have  any  privilege  on  this 
database 

mysqi -get -login . pi  - gets  superuser  login  and  password 
mysqi -get -login . pi . sh  - gets  superuser  login  and  password 
mysqi -revoke-ail  - revokes  all  user  privileges  on  database 
mysqi-revoke-aii . sh  - revokes  all  user  privileges  on  database 
mysqi-create-user  - creates  MySQL  user 
mysqi-create-user . sh  - creates  MySQL  user 
mysqi-deiete-user  - deletes  MySQL  user 
mysqi-deiete-user . sh  - deletes  MySQL  user 

mysqi -grant -priv  - grants  given  privilege  on  given  database  to  given  user 
mysqi-grant-priv . sh  - grants  given  privilege  on  given  database  to  given  user 
mysqi-suspend-user  - suspends  MySQL  user 

mysql-suspend-user . sh  - suspends  MySQL  user 

All  scripts  accept  some  command  line  parameters.  All  scripts  consist  of  two  parts.  The 
first  part,  typically  without  extension,  sets  some  necessary  variables  and  then  calls  out 
the  second  part  of  the  script  under  sudo. 

INFO:  f ix_perm.  sh  scripts  sets  the  needed  owner  and  rights  to  mysqi  scripts. 


WARNING:  Some  of  these  scripts  are  different  on  the  FreeBSD  systems,  so  copy  the 
Corresponding  script  versions  from  /hsphere/ shared/ scripts/FreeBSD. 
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Getting  Remote  Access  to  MySQL  Logical 
Server 


By  default,  MySQL  client  connects  to  MySQL  server  on  localhost  (127.0.0.1).  It  is 
possible  to  configure  MySQL  client  to  use  the  -h  option  to  connect  to  the  MySQL 
server  remotely  by  the  logical  server  IP: 

mysql  -h  <mysql_logical_server_ip> 

This  feature  is,  in  particular,  required  in  some  custom  MySQL  configurations  where  one 
MySQL  client  (bound  to  the  physical  server  IP)  connects  to  several  MySQL  servers  on 
different  boxes  (bound  to  the  logical  server  IPs). 

> To  enable  or  disable  remote  access  to  particular  MySQL  logical  servers  in  the  Control 
Panel: 

1 Go  to  the  admin  Control  Panel,  E. Manager  menu,  L.Server. 

2 Choose  a MySQL  logical  server  from  the  list  of  logical  servers. 

3 Under  Additional  Options,  check  or  uncheck  the  option  Remote  Access  To 
MySQL  Server  and  press  Set: 


Additional  options 

Remote  Access  To  MySQL  Server 

r Set  | 

4 Confirm  your  choice  on  the  page  that  appears. 


WARNING:  1)  Remote  access  to  MySQL  server  is  currently  incompatible  with  Parallels 
H-Sphere  mail  system!  You  must  not  enable  remote  MySQL  access  on  physical 
servers  with  live  mail! 

2)  You  must  not  change  logical  server  IP  on  or  add  another  server  IP  to  MySQL  logical 
server  where  remote  access  is  enabled  to! 
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Enabling  Linked  Tables  in  phpMyAdmin 

Newer  versions  of  phpMyAdmin  give  the  following  error  if  not  configured  accordingly: 

"Error 

The  additional  features  for  working  with  linked  tables  have  been 
deactivated . " 

These  features  include  bookmarks,  comments,  SQL-history,  PDF  generation,  field 
contents  transformation,  etc. 

> To  enable  new  phpMyAdmin  features: 

1 Log  into  the  web  server  as  root.  This  must  be  the  web  server  where 
phpMyAdmin  is  installed.  The  ID  of  this  logical  server  is  specified  in 

/hsphere/ local /home /cpanel / shiva/ psof t_conf ig/hsphere 
.properties  on  the  CP  server. 

2 Create  phpmyadmin  database.  If  you  are  running  Web  and  MySQL 
servers  on  the  same  box: 

mysql  -u  root  -p<password>  < 

/hsphere/ shared/apache/htdocs/phpMyAdmin/ scripts/ create_tables 
. sql 

If  they  are  on  different  boxes: 

mysql  -h  <MYSQL_SERVER_IP>  -u  root  -p<PASSWORD>  < 

/hsphere/ shared/apache/htdocs/phpMyAdmin/ scripts/ create_tables 
. sql 

3 Give  necessary  permissions  to  the  controluser. 

If  you  are  running  Web  and  MySQL  servers  on  different  boxes,  first  log  into  the 
MySQL  server  as  root. 

mysql#  GRANT  SELECT,  INSERT,  UPDATE,  DELETE  ON  phpmyadmin.*  TO 
' phpuser ' @ ' % ' ; 

4 Enter  the  following  values  in  the  file 

/hsphere/ shared/ apache /htdocs / phpMyAdmin/ config.inc.p 

hp  on  the  web  server: 


$cf gServers 

[1] 

[ ' pmadb ' ] = ' phpmyadmin ' ; 

$cf gServers 

[1] 

[ ' table  info ' ] 

= 'pma  table  info'; 

$cf gServers 

[1] 

[ ' pdf  pages ' ] = 

'pma  pdf  pages'; 

$cf gServers 

[1] 

[ ' history ' ] = ' 

pma  history'; 

$cf gServers 

[1] 

[ ' column  info ' ] 

= 'pma  column  info'; 

$cf gServers 

[1] 

[ ' table  coords ' 

] = 'pma  table  coords'; 

$cf gServers 

[1] 

[ ' relation ' ] = 

'pma  relation'; 

$cf gServers 

[1] 

[ ' bookmarktable 

']  = 'pma  bookmark'; 
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Changing  MySQL  Root  Password 

This  document  explains  how  to  change  the  root  user  password  in  MySQL  access 
privilege  database. 

In  this  section: 


Option  1 218 

Option  2 219 


Option  1 

1 Login  as  root  to  the  box  with  the  MySQL  server. 

2 Stop  MySQL  server  (on  page  56). 

3 Open  the  mysql  server  startup  script.  This  is  the  file  you  have  just 
executed  to  stop  MySQL  server. 

4 Find  the  line  that  contains  the  mysqld_safe  command  and  add  -- 

skip-grant-tables  as  its  parameter. 

5 Start  MySQL  server  (on  page  56). 

6 Login  as  the  mysql  user  and  connect  to  the  mysql  user/permission 
database  and  run  the  update  queries: 

# mysql  -u  root  mysql 

mysql>  UPDATE  user  SET  Password=PASSWORD ( ' newrootpassword ' ) 
WHERE  User='root'; 
mysql > FLUSH  PRIVILEGES; 

replacing  newrootpassword  with  the  new  root  password  to  the  box  with  the 
MySQL  server. 

7 Exit  mysql  database  by  typing  \q. 

8 Exit  mysql  user  console  by  typing  exit. 

9 Stop  MySQL  server  (on  page  56). 

10  Open  the  mysql  server  startup  script  and  remove  the  --skip- 
grant-tables  parameter  you  added  above. 

11  Start  MySQL  server  (on  page  56). 

12  Open  the  file  -mysql/  .my.  cnf  and  update  the  password  in  the 
corresponding  line. 
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Option  2 

1 Stop  the  MySQL  daemon: 

kill  'pidof  mysqld' 
ps  auxw  | grep  mysql 

2 Temporarily  create  a text  file  in  the  following  location: 

/hsphere/local/config/mysql/f i le_name 

This  file  must  contain  a string  with  an  sql  command  similar  to  this  one: 

SET  PASSWORD  FOR  ’ root ' @ ' localhos t ' = 

PASSWORD ( ' your_new_mysql_password ' ) ; 

3 Manually  start  mysql  with  a special  option: 

mysqld_safe  --init-file=/hsphere/local/ conf ig/mysql/ file_name 
& 

4 Check  whether  the  new  password  is  working: 
mysql  -p 

If  everything  is  fine,  you'll  get  a screen  like  this: 

Welcome  to  the  MySQL  monitor.  Commands  end  with  ; or  \g. 

Your  MySQL  connection  id  is  2 to  server  version:  5.0.27- 
standard-log 

Type  'help; ' or  ' \h ' for  help.  Type  ' \c'  to  clear  the  buffer. 

5 Kill  mysql: 

kill  'pidof  mysqld' 

6 Remove  the  temporary  file: 

rm  -f  /hsphere/local/config/mysql/file_name 

7 Start  MySQL  server  (on  page  56). 

8 Open  the  file  -mysql/  .my.  cnf  and  update  the  password  in  the 
corresponding  line. 

This  option  2 is  simpler,  faster  and  more  secure  than  the  first  one  as  there  is  neither 
editing  the  script  rc . d/mysqid  startup  nor  using  the  command  — skip-grant- 
tables. 
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Moving  MySQL 

This  section  explains  how  to  move  MySQL  service  between  boxes  of  an  Parallels  H- 
Sphere  cluster. 

In  this  section: 


Step  1.  Preparing  Servers 220 

Step  2.  Moving  MySQL  Content 220 

Step  3.  Updating  System  Database 220 

Step  4.  Updating  Resellers'  Server  Aliases 221 

Step  5.  Synchronizing  MySQL  Content 221 

Step  6.  Finalizing  the  Migration 221 

Step  7.  Checking  Functionality 221 


Step  1 . Preparing  Servers 

1 Update  your  Parallels  H-Sphere  to  the  latest  version. 

2 Apply  the  latest  MySQL  update,  if  any,  after  the  installation  of  your 
Parallels  H-Sphere. 

3 Prepare  a new  box  with  MySQL  (on  page  212)  using  Parallels  H- 
Sphere  installer. 

4 In  E. Manager,  disable  signup  for  the  MySQL  server. 

Step  2.  Moving  MySQL  Content 

1 Log  into  the  targer  box  as  root: 
ssh  root@< TARGET_MYSQL_SERVERJP> 

2 Stop  MySQL  service  (on  page  56). 

3 Move  the  mysql/  directory  from  the  source  server: 

rsync  -arzgop  -e  ssh  rootQ<SOURCE_MYSQL_SERVERJP> : ~mysql/ 
~mysql/ 

4 Start  MySQL  service  (on  page  56). 

Step  3.  Updating  System  Database 

1 Stop  the  Control  Panel  (on  page  54). 
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2 Log  into  the  Parallels  H-Sphere  system  database  (on  page  65)  and 
run  the  following  queries: 

update  1 server  set  p server  id=<TARGET  PHYSICAL  SERVER  ID> 
where  id=<MYSQL_LOGICAL_SERVER__ID>; 

(1  record) 

update  l_server_ips  set  ip= ' <TARGET_MYSQL_SERVER_IP> ' , 
mask= ' <TARGET_MYSQL_SERVER_MASK> ' where 
l_server_id=<MYSQL_LOGICAL_SERVER_ID>  and  flag=4; 

(1  record) 

3 Start  the  Control  Panel  (on  page  54). 

Step  4.  Updating  Resellers'  Server  Aliases 

As  the  cpanel  user,  run  ServerAliasRenamer: 

java  psoft . hsphere . tools . ServerAliasesRenamer  --lserver 

<MYSQL_LOGICAL_SERVER_ID> 

Step  5.  Synchronizing  MySQL  Content 

1 Stop  MySQL  service  on  the  source  box. 

2 Repeat  all  of  Step  2 above. 

3 If  the  source  box  has  a mail  service,  log  in  there  and  start  MySQL 
service. 

Step  6.  Finalizing  the  Migration 

1 Go  to  E. Manager  ->  DNS  Manager  and  choose  to  edit  the  main  service 
DNS  zone.  Change  the  IP  in  the  A DNS  record  for  the  MySQL  server. 

2 Open  the  file  conifig.  inc.php  in  the  PhpMyAdmin  directory. 
Change  the  IP  of  MySQL  server  in  $cfgServers  [ $ i ] [ ' host ' ] . $i 
is  the  number  of  the  MySQL  server  in  PhpMyAdmin  configuration: 

$i=l r 2 , . . 

3 Check  if  any  of  the  customer  scripts  use  the  MySQL  server  IP  and 
update  all  instances. 

4 Install  (http://www.quietsche-entchen.de/download/tcpproxy-2.0.0- 
betal  5.tar.qz)  and  configure  (http://www.quietsche-entchen.de/cqi- 
bin/wiki.cqi/-wiki/proxies/TcpProxy)  TCP  proxy  on  the  old  server  to 
ensure  that  MySQL  hostname  resolves  to  the  new  IP  address  during 
the  propagation  period. 

Step  7.  Checking  Functionality 

Now  that  you  have  finished  the  migration,  visit  a few  user  websites  that  use  MySQL 
and  verify  that  everything  works  smoothly. 
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Moving  MySQL  Accounts 


WARNING:  The  undermentioned  procedure  is  recommended  for  experienced  Parallels 
H-Sphere  owners  only! 


All  MySQL  resources  of  the  particular  Parallels  H-Sphere  account  are  called  MySQL 
account  hereinafter.  The  following  steps  explain  how  to  move  all  databases  of  a 
particular  Parallels  H-  Sphere  account  to  a new  logical  MySQL  server  and  apply 
changes  to  the  Parallels  H-Sphere  database. 

> To  move  MySQL  account: 

1 Log  into  the  source  MySQL  server  and  get  MySQL  root  password  that 
will  be  generated  after  entering  the  following  command: 

# cat  ~mysql/ .my . cnf 

2 Export  user  account  databases  on  source  MySQL  server  with  the  help 
of  mysqldump  utility: 

# mysqldump  -Q  -uroot  -p  DBNAME  > DBNAME . sql 
where  dbname  is  the  database  name. 

This  should  be  applied  to  every  user  database  within  the  account. 

3 Dump  user  database  privileges  on  source  MySQL  server: 

# mysqldump  -c  -e  -Q  -t  my sql  -uroot  -p  db  -w  "db  like 
' USERNAME_% ' " > USERNAME_mysql . db . sql 

where  username  is  an  Parallels  H-Sphere  user  prefix  for  database. 

4 Log  into  CP  server.  Change  MySQL  logical  server  id  for  the  account: 

# su  - cpanel 

# java  -Xms64M  -Xmx256M  psoft . hsphere . tools . ChangeLServerld  -a 
ACC_ID  --from  OLD_LID  — to  NEW_LID 

where: 

acc  id  - the  account  id 

old_lid  - source  logical  mysql  server  ID 

new_lid  - target  mysql  logical  server  ID 

5 Create  empty  databases  on  the  target  MySQL  server: 

# su  - cpanel 

# java  -Xms64M  -Xmx256M  psoft . hsphere . tools . PhysicalCreator  - 
rg  mysql  -co  -lid  NEW_LID  -accs  ACC_ID 

6 Transfer  all  dbname  . sql  and  usERNAME_mysqi . db . sql  files  from 
the  source  server  to  the  target  MySQL  server. 

7 Log  into  the  target  MySQL  server  and  get  MySQL  root  password  that 
will  be  generated  after  entering  the  following  command: 

# cat  ~mysql/ .my . cnf 
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8 

9 

# mysql  -uroot  -p  mysql  < USERNAME_mysql . db . sql 

# mysqladmin  reload  -p 

10  Restart  Parallels  H-Sphere  CP  (on  page  54). 

11  Make  sure  to  check  MySQL  dbs  functionality  on  the  target  server.  If  it 
is  ok,  you  may  delete  MySQI  databases  from  the  source  server  by 
running  the  following  commands: 

/hsphere/ shared/ scripts/mysql-drop-database  DBNAME 
/hsphere/ shared/ scripts/mysql-delete-user  USERNAME 


Perform  steps  2, 3, 8, 9,1 1 for  each  MySQL  db  and  user  of  the  current  Parallels  H- 
Sphere  account  on  the  source  MySQL  server. 


Import  databases: 

# mysql  -uroot  -p  DBNAME  < DBNAME . sql 

Restore  user  database  privileges: 
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PostgreSQL  Server 


This  chapter  describes  some  task  you  may  need  to  perform  on  your  Parallels  H-Sphere 
PostgreSQL  server. 

PostgreSQL  log  file  is  /var/iog/pgsqi. 

PostgreSQL  server  comes  with  PhpPgAdmin  (http://phppqadmin.sourceforqe.net/) 
which  is  a PostgreSQL  administration  Web  interface  written  in  PHP.  It  is  installed  with 
PostgreSQL  server  as  a hsphere-phppgadmin-<vers/on>-<bu/7c(>  package,  where 
<version>  is  PhpPgAdmin  version,  and  <build>  is  this  package's  build  number. 

IPhpPgAdmin  installation  directory  is 

/hsphere/ shared/ apache/ht docs /phpPgAdmin. 


In  this  chapter: 

Installing  PostgreSQL  Server 224 

Backing  Up  PostgreSQL  Database 227 

Using  VACUUM  Utility 227 

Running  PostgreSQL  Scripts 228 

Changing  Postgres  User  Password 229 

Localizing  PostgreSQL 230 

Configuring  Parallels  H-Sphere  to  Use  Non-Default  MySQL/PostgreSQL  Versions 
Choosing  Remote  Web  Logical  Servers  for  phpMyAdmin/phpPgAdmin  Frontends232 
Downgrading  Postgres 233 
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Installing  PostgreSQL  Server 

Below  is  the  procedure  of  installing  PostgreSQL  database  software  and  adding 
PostgreSQL  server  to  Parallels  H-Sphere  cluster. 


In  this  section: 


Step  1.  Checking  for  PostgreSQL 225 

Step  2.  Downloading  PostgreSQL 225 

Step  3.  Installing  PostgreSQL 226 

Step  4.  Configuring  PostgreSQL 226 
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Step  1 . Checking  for  PostgreSQL 

First,  check  if  you  have  PostgreSQL  database  server  already  installed. 

You  may  do  this  by  entering  the  following  command  into  your  command  prompt: 

which  psql 

If  you  get  the  following  (or  similar): 

/usr/ local /pgsql/bin/psql 

this  means  you  have  already  got  PostgreSQL  database  software  installed. 

Using  the  rpm  -q  command  (on  RedPlat  servers)  is  an  alternative  way  to  check  if 
PostgreSQL  is  installed.  Type  the  following  command  in  your  command  prompt: 

rpm  -qa  | grep  postgresql 

If  you  get 

postgresql-7 . 3 . 4-x 

or  something  alike  when  the  command  is  executed,  it  will  mean  that  you  already  have 
PostgreSQL  database  software  installed. 

Now  you  may  use  the  existing  one  or  install  a later  version  of  PostgreSQL. 

Step  2.  Downloading  PostgreSQL 

Note:  skip  this  step  if  PostgreSQL  has  been  already  installed. 


If  you  don't  have  PostgreSQL  installed,  you  will  need  to  download  PostgreSQL  from 
binary  RPM  distribution  from  www.postaresal.org  or  its  mirror  sites. 


Find  RPM  file  which  is  usually  stored  in  the  software/download  directory  and 
download  it. 
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Step  3.  Installing  PostgreSQL 

Install  the  PostgreSQL  database  software.  Do  this  by  the  following  command: 

On  Red  Hat  servers: 

rpm  -i  postgresql_rpm_f ile_name 

where  postgresqi_rpm_f  iie_name  is  PostgreSQL  binary  RPM  distribution. 

On  FreeBSD  servers: 

pkg_add  postgresql_pkg_f ile_name 

where  postgresqi_pkg_f  iie_name  is  PostgreSQL  package  for  FreeBSD. 

Step  4.  Configuring  PostgreSQL 

1 . Prior  to  configuration,  you  need  to  start  PostgreSQL  for  the  first  time  to  initialize  the 
PostgreSQL  service  database  and  to  create  the  necessary  files  and  directories. 

On  RedHat  servers,  PostgreSQL  service  is  initialized  automatically  on  the  first 
PostgreSQL  start: 

/ etc/rc . d/init . d/postgresql  start 

On  FreeBSD  servers,  you  need  to  initialize  it  manually  before  you  start  PostgreSQL: 

su  - pgsql  -c  initdb 

/usr/local/etc/rc . d/010 .pgsql . sh  start 

2.  To  configure  the  access  to  PostgreSQL  DBs,  go  to  PostgreSQL  home  directory.  It  is 
usually  /usr/ local/ pgsql.  To  find  out  what  is  the  path  to  PostgreSQL  home 
directory,  login  as  postgres  user  under  root  and  type  pwd: 

# su  - postgres 

# pwd 

or,  finger  postgres  to  get  info  about  the  postgres  user: 

# finger  postgres 


In  this  directory,  find  the  data/pg_hba.  conf  file.  Open  it  and  find  the  records  similar 
to  the  ones  below: 


TYPE 

DATABASE 

USER 

IP_ADDRESS 

MASK 

AUTHTYPE 

MAP 

local 

all 

all 

trust 

host 

all 

all 

127.0.0.1 

255.255.255.255 

password 

host 

all 

all 

0.0. 0.0 

0.0. 0.0 

password 
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If  the  'authtype'  parameter  is  set  to  trust,  you  must  change  the  authentication 
option  to  password. 

* For  more  detailed  configuration,  see  pg_hba.  conf  file. 

Warning:  If  during  the  update  process  you  get  the  message: 

WARNING:  pg  hba.conf  must  be  configured  more  strictly. 

it  means  that  pg_hba . conf  for  a given  Postgres  database  should  be  configured  to 
restrict  IP  access  to  Postgres  databases  from  outside  the  Parallels  H-Sphere  cluster.  It 
is  especially  important  to  ensure  that  IP  access  to  the  Parallels  H-Sphere  system 
database  is  provided  only  from  CP. 

See  also:  Setting  password  for  the  PostgreSQL  user  (on  page  229)  (postgres  on 
RedHat,  pgsqi  on  FreeBSD). 


Backing  Up  PostgreSQL  Database 

Back  up  the  PostgreSQL  home  directory  or  make  the  database  export  by  the  means  of 
PostgreSQL.  Type  'man  psqi'  or  see  Postgres  documentation 
(http://www.postqresql.org/docs/)  for  details. 


Using  VACUUM  Utility 

The  Postgres  VACUUM  command  enables  to  clean  up  the  server  transactions. 
Enter  the  psqi  server: 

# psqi  database_name  [user_name] 

In  the  psqi  command  line,  type  the  'vacuum  full’  command: 

vacuum  full; 

Or,  write  a shell  script  performing  this  procedure  and  add  it  to  cron  jobs  on  the 
PostgreSQL  server  to  be  launched  regularly. 


Note:  vacuum  is  a time-consuming  procedure;  it  may  take  up  to  several  hours  to 
complete! 
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Running  PostgreSQL  Scripts 

On  the  PostgreSQL  database  box  in  the  /hsphere/shared/scripts  directory,  the 
following  scripts  are  installed: 

pgsql-change-user-password  - Changes  user  password 
pgsql-change-user-password.  sh  - changes  user  password 
pgsqi-create-db  - creates  PostgreSQL  database 
pgsqi-create-db . sh  - creates  PostgreSQL  database 
pgsqi-create-user  - creates  PostgreSQL  user 
pgsqi-create-user . sh  - creates  PostgreSQL  user 
pgsqi-db-size  - calculates  database  size 
pgsqi-db-size  .pi  - calculates  database  size 
pgsqi-deiete-user  - deletes  PostgreSQL  user 
pgsqi-deiete-user . sh  - deletes  PostgreSQL  user 
pgsqi-drop-database  - drops  PostgreSQL  database 
pgsqi-drop-database . sh  - drops  PostgreSQL  database 
pgsqi -get-login  - gets  PostgreSQL  superuser  login  and  password 
pgsqi -get-login. pi  - gets  PostgreSQL  superuser  login  and  password 
pgsqi-resume-user  - resumes  the  suspended  user 
pgsqi-resume-user . sh  - resumes  the  suspended  user 
pgsqi-setenv  - sets  PostgreSQL  environment  variables 
pgsqi-suspend-user  - suspends  PostgreSQL  user 
pgsqi-suspend-user . sh  - suspends  PostgreSQL  user 

All  scripts  accept  some  command  line  parameters.  All  scripts  consist  of  two  parts.  The 
first  part,  typically  without  extension,  sets  necessary  variables  and  then  calls  the 
second  part  of  the  script  under  sudo. 

INFO:  f ix_perm.  sh  scripts  sets  needed  owner  and  rights  to  Postgres  scripts. 


PostgreSQL  Server  229 


WARNING:  Some  of  these  scripts  are  different  on  FreeBSD  systems,  so  copy 
corresponding  versions  Of  scripts  from  /hsphere/shared/scripts/FreeBSD. 


Changing  Postgres  User  Password 

Changing  the  password  for  the  postgres  user  (pgsqi  in  FreeBSD)  differs  depending 
on  the  version  of  PostgreSQL  installed.  To  check  the  version,  type  under  root: 

# psql  --version 

PostgreSQL  7.4.7  is  used  in  the  latest  versions  of  Parallels  Pi-Sphere  for  both  the 
Parallels  Pi-Sphere  system  database  (on  page  63)  and  user  databases  (on  page  224). 

The  postgres/pgsqi  password  is  changed  in  the  PostgreSQL  service  database.  This 
is  a more  secure  way  than  having  the  passwords  stored  in  a file. 

1 Run  under  root: 

In  RedHat: 

psql  -d  tempiatei  -u  postgres  (enter  the  templatel  service  database) 

alter  user  postgres  with  password  'postgres  password';  (run 
query  to  change  the  password) 

In  FreeBSD: 

psql  -d  templatel  -U  pgsqi 

alter  user  pgsqi  with  password  'pgsqi  password' ; 

2 Restart  Postgres  (on  page  55)  to  apply  changes. 


230  PostgreSQL  Server 


Localizing  PostgreSQL 

> To  set  up  a custom  language  support  when  entering  data  into  PostrgreSQL: 

1 Recompile  PostgreSQL  using  the  following  keys: 

— enable-locale  (enable  locale  support) 

— enable-recode  (enable  Cyrillic  recode  support) 

— with-mb=wiN  (enable  multi-byte  support,  e.g.  WIN) 

2 Create  Parallels  H-Sphere  database  supporting  the  new  encoding 
(e.g.  WIN). 

NOTE:  if  the  browser  encoding  does  not  agree  with  the  database  encoding,  it  is 
impossible  to  guarantee  a correct  record  in  the  database. 


In  the  ~cpanel/ shiva/psoft  conf  ig/hsphere  .properties  configuration  file, 
replace 

DB  URL  = j dbc : postgresql : //127 . 0 . 0 . 1/hsphere 

with 

DB_URL  = 

j dbc : postgresql : //127 . 0 . 0 . 1/hsphere  ?charSet =<YOUR_LANGUAGE_ENCODIN 
G> 

For  instance,  Russian  language  support  takes  the  following  line: 

DB  URL  = j dbc : postgresql : //127 . 0 . 0 . l/hsphere?charSet=WIN 


Configuring  Parallels  H-Sphere  to  Use 
Non-Default  MySQL/PostgreSQL  Versions 

You  can  use  versions  of  MySQL/PostgreSQL  other  than  those  included  into  Parallels 
H-Sphere  updater.  For  instance,  when  updating  to  Parallels  H-Sphere  3.0  with  MySQL 
5.0.x  and  Postgres  7.4.x  there  may  be  a necessity  to  use  MySQL  4.1  .x  included  into 
Parallels  H-Sphere  2.5.0  or  Postgres  8.0.x  enabled  for  a certain  operational  system.  In 
such  a situation  Parallels  H-Sphere  updater  allows  excluding  default  versions  of 
MySQL/PostgreSQL,  as  well  as  updating  and  configuring  them  by  means  of  native 
system  package  managers. 

> To  make  sure  CP  properly  works  with  such  custom  MySQL/PostgreSQL  versions: 

1 Exclude  MySQL/PostgreSQL  from  Parallels  H-Sphere  3.0+  updater 

To  exclude  the  above  mentioned  packages,  run  one  of  the  following  updater 
commands: 
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exclude-mysql=show | add | del 
exclude -postgresql=show | add | del 

If  custom  MySQL/PostgreSQL  has  to  be  set  not  for  all  MySQL/PostgreSQI  logical 
servers,  set  a list  of  specific  IPs.  To  do  this,  refer  to  the  section  on  Parallels  hl- 
Sphere  Update  Package  of  the  Update  Guide. 

2  Configure  MySQL/PostgreSQL  to  support  non-default 
MySQL/PostgreSQL  versions 

> To  add  an  Parallels  H-Sphere  configuration  to  MySQL  and  PostgreSQI  services: 

For  MySQL: 

1 Create  ~mysql/.my.cnf  file  which  contains: 

cat  ~mysql/ .my . cnf 
[ client ] 
user=root 
pas  sword= PASSWORD 

2 Set  necessary  file  permissions: 

chmod  0400  ~mysql/ .my . cnf 
chown  mysql:mysql  ~mysql/ .my . cnf 

3 Configure  /etc/my . cnf  file  (if  any)  according  to  your  needs 

For  PostgreSQL: 

1 Create  pgsql  (FreeBSD)  or  postgres  (Linux)  database  user, 
hereafter  pguser 

2 If  you  customize  CP  PostgreSQL,  create  wwwuser,  i.e.  Parallels  H- 
Sphere  main  PostgreSQL  database  user 

3 According  to  PGDATADIR  variable  (from  startup  file),  create: 

$PGDATADIR  /global/pg_ps 
and  add  a string  in  the  following  format: 

user  password 

4 Set  permissions: 

chown  $PGUSER: $ PGUSER  $ PGDATADIR  /global/pg_j>s 
chmod  600  $PGDATADIR  /global/pg_j?s 

5 Configure  ~$PGDATADiR/pg_hba . conf  by  setting  the  list  of  subnets 
and  providing  password  type  for  validation 

6 If  you  customize  a CP  PostgreSQL,  make  sure  you  have  correctly  set 
a wwwuser  access  password  to  a database.  You  can  check  in  the 

~cpanel / shiva/  psof t_conf  ig/h  sphere  .properties  file 

7 Provide  a PostgreSQL  logs  rotation  according  to  syslog  facility 
specified  in  pgdatadir/ postgresqi . conf  configuration  file. 

Note:  to  check  that  MySQL/PgSQL  is  properly  configured,  run  the  following  script: 

/hsphere/pkg/ scripts /uprocedure/dbs_check 
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Choosing  Remote  Web  Logical  Servers 
for  phpMyAdmin/phpPgAdmin  Frontends 

Parallels  H-Sphere  logical  web  server  is  by  default  installed  on  a physical  box  together 
with  PostgreSQL/MySQL  logical  servers,  thus  phpMyAdmin  and  phpPgAdmin  frontends 
use  Apache  on  the  same  server. 

It  is  possible  to  choose  an  alternative  remote  Web  logical  server  for  phpMyAdmin  and 
phpPgAdmin.  Now  you  can  configure  one  phpMyAdmin/phpPgAdmin  frontend  to 
manage  multiple  database  servers. 

> To  choose  remote  Web  servers  for  phpMyAdmin: 

1 Login  as  cpanel  user  (on  page  65)  and  set  the  following  property  in 

~cpanel / shiva/ psof t_conf ig/hsphere .properties: 

EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  54)  to  apply  changes. 

Important:  If  external_service_usage  is  not  set  or  is  not  TRUE,  you  will  not 
be  able  to  choose  an  external  Web  server  for  phpMyAdmin! 

2 In  admin  CP,  go  to  E.Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  MySQL  logical  server,  and  Choose  Unix  Hosting  server  for 
phpMyAdmin  under  Additional  Options. 

3 Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 
hspackages  reconfig=frontend 

Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 

4 To  move  phpMyAdmin  content  to  respective  remote  Web  logical 
server  location,  run  the  following  script  on  the  source  box: 

/hsphere/pkg/ scripts/uprocedures/dbs_content  -h 

Usage:  dbs_content  [ -h  ] -d  dbtype  [ -i  ip  ] [ -p  password  ] 

dbtype:  horde  or  spamassassin  or  phpmyadmin 

ip:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from  current 
external  MySQL  server  to  another  one  or  MySQL  service,  located  on  the 
corresponding  mail  logical  server. 

password:  this  option  is  required  only  in  the  case,  if  redefinition  took  place  from 
current  external  MySQL  server  to  MySQL  service,  located  on  the  corresponding 
mail  logical  server. 

> To  choose  remote  Web  servers  for  phpPgAdmin: 
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1 Login  as  cpanel  user  (on  page  65)  and  set  the  following  property  in 

~cpanel / shiva/ psof t_conf ig/hsphere .properties: 

EXTERNAL_SERVICE_USAGE  = TRUE 

Then,  restart  Parallels  H-Sphere  (on  page  54)  to  apply  changes. 

Important:  If  external_service_usage  is  not  set  or  is  not  TRUE,  you  won't  be 
able  to  choose  an  external  Web  server  for  phpPgAdmin! 

2 In  admin  CP,  go  to  E. Manager  ->  Servers  ->  L.Servers,  proceed  to  settings 
for  this  PostgreSQL  logical  server,  and  Choose  Unix  Hosting  server 
for  phpPgAdmin  under  Additional  Options. 

Note:  For  security  reasons,  it  is  not  possible  to  choose  Web  logical  server  on  the 
CP  box  for  phpPgAdmin. 

3 Login  to  CP  server  as  root,  download  and  run  the  Parallels  H-Sphere 
3.0  RC  4+  updater  with  the  hspackages  reconfig  option: 
hspackages  reconfig=frontend 


Note:  Regular  Parallels  H-Sphere  update  to  3.0  RC  4 and  up  automatically  includes 
the  reconfig  option.  However,  for  best  performance  we  recommend  running 
Parallels  H-Sphere  updater  with  this  option  separately. 


Downgrading  Postgres 

Parallels  H-Sphere  works  correctly  only  with  Postgres  7.x.  Thus,  if  you  have 
accidentally  upgraded  Postgres  package  on  your  CP  server  to  version  8.x  and  higher, 
you  need  to  perform  its  downgrade  to  the  version  you  had. 

> To  downgrade  Postgres: 

1 Log  into  the  control  panel  server  as  root. 

2 Back  up  CP  postgres  home  dir. 

3 Back  up  the  file  /etc/init . d/postgresql. 

4 Stop  the  control  panel,  (on  page  54) 

5 Stop  Postgres: 

/etc/rc.d/init.d/postgresql  stop 

6 Check  what  postgres  packages  are  installed: 

rpm  -qa  | grep  -i  postgres 

7 Uninstall  postgres: 

rpm  -e  --nodeps  'rpm  -qa | grep  -i  postgres' 

8 Install  an  earlier  version  of  postgres  packages.  The  installations  are 
available  on  your  CP  server  in  the  directory 

/hsphere  / install/pkg/  <CP_OS>/ 

9 Start  Postgres: 

/ etc/ rc . d/ init . d/postgresql  start 
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10  Start  the  control  panel,  (on  page  54) 
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Windows  Servers 

This  chapter  is  dedicated  to  Parallels  H-Sphere  Windows  hosting  server  configuration. 
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MSI  Packages 

Parallels  H-Sphere  Winbox  installation  and  update  is  performed  from  MSI  packages 
each  responsible  for  a particular  functionality: 

■ HsCore  - core  of  Parallels  H-Sphere  Winbox  service 

■ Hsinstaiier  - Parallels  H-Sphere  Winbox  installer 

■ HsGenerai  Ho  sting  - provides  FTP  hosting  services 

■ hsmssqL  - Parallels  H-Sphere  MSSQL  hosting  server  (requires  MSSQL  server 
installed  on  the  box) 

■ HsRSync  - RSync  utitity 

■ HsWeb  - provides  Parallels  H-Sphere  Web  resources  for  Windows  hosting 

■ HsAspNetSqiEMan  - supports  ASP.NET  Enterprise  manager 

■ HsSharePoint  - SharePoint  hosting  (requires  SharePoint  installed) 

■ HsCoidFusion  - ColdFusion  hosting  (requires  ColdFusion  installed) 

■ HsWebalizer  - Webalizer 

■ HsUrchin  - integrates  the  Google  Analytics  tool  (requires  Urchin  installed) 

■ HsMiva  - integrates  Miva  tool  (requires  Miva  installed) 

■ HsPerl  - Perl 

■ HsAWStats  - AWStatS 

■ HsStats  - Winbox  statistics  resource 

■ hsphp  - PHP  hosting,  includes  both  PHP  4 and  5 version 

■ HsWebSheii  - WebShell  Web  File  Manager 

■ HsOsCommerce  - OsCommerce 

■ HsPhpBB  - PhpBB 

■ HsEasyAppSvc  - provides  EasyApp  service  to  enable  installation  of  EasyApp 
collection 

Each  package  filename  has  the  following  notation: 

<PACKAGE_TITLE>_<HS_VERSION>  . <BUILD> . <TIMESTAMP> . msi 
where: 

■ <PACKAGE_TITLE>  is  the  name  of  the  package  (see  the  list  above) 

■ <HS_VERSION>  is  Parallels  H-Sphere  version 

■ <BUILD>  is  the  package  build 

■ <TIMESTAMP>  is  the  package  build  timestamp  (days  from  1 Jan  2000) 

Example:  HsGenerai  Ho  sting  3. 2. 152. 3195. msi. 


In  this  section: 
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Download  and  Installation 237 

Packages  Requiring  Third-party  Software 238 

Dependencies  T ree 238 


Download  and  Installation 

Parallels  H-Sphere  MSI  packages  are  downloaded  from  the 
http://download.hsphere.parallels.com/shiv/HS/WINDOWS/  location. 

There  can  be  several  cases  of  installing  these  packages: 

■ Automatic 

The  first  step  is  downloading  and  running  the  HsCore  package.  Installation/update 
of  the  rest  of  the  packages  is  managed  from  the  admin  CP  by  means  of  the  Update 
Wizard.  The  wizard  runs  them  from  the 

<HS_HOME>\data\services\installer  folder,  where  <HS_HOME>  is 
Parallels  H-Sphere  home  location  (C:\Program  Files\HSphere  by 
default ) 

In  case  of  upgrade  from  H-Sphere  2. 5/3.0: 

1 . Older  H-Sphere  home  folder  will  be  forcefully  moved  to  C:\Program 
Files\HSphere. 

2.  Older  PHP  packages  will  be  replaced  by  HsPHP. 

3.  Older  EasyApp  collection  will  be  built  into  a separate  MSI  package  and  installed 
into  the  H-Sphere  Winbox  framework. 


■ Istallation  of  the  Bundles 

Download  and  run  the  Windows  server  installation  bundles  in  accordance  with  the 
hosting  type: 

■ Windows  Web  hosting:  HS_WinHosting_Bundle<HS_VE/?S/OW> . exe 

■ MS  SQL  hosting:  hs_mssql _Bundle _<HS_VERSION> . exe 

■ Windows  Web  + MS  SQL  hosting: 

HS  WinHosting  MSSQL  Bundle  <HS_VERSiON> . exe 

■ Manual 

Not  recommended!  You  can  also  manually  install/update  Parallels  H-Sphere  Winbox 
by  downloading  these  packages  and  running  them  one  by  one,  according  to  their 
dependencies. 
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Packages  Requiring  Third-party  Software 

HsMSSQL,  HsSharePoint,  HsColdFusion,  HsUrchin  and  HsMiva  integrate  third- 
party  products  into  Parallels  H-Sphere  environment  and  require  respective  software 
installed.  Please  refer  to  separate  documents  for  specific  guidelines  on  their 
configuring: 

■ SharePoint  (on  page  247) 

■ ColdFusion  (on  page  257) 

■ Miva  (on  page  458) 

■ Urchin  (on  page  463) 


Dependencies  Tree 

Parallels  Pi-Sphere  Update  Wizard  installs  the  packages  in  the  following  sequence: 


HsCore 

I — Hslnstaller 
I—  HsMSSQL 
I — HsGeneralHosting 
I — HsRsync 
I—  HsWeb 

I—  HsAspNetSqlEMan 
I — HsSharePoint 
I — HsColdFusion 
I — HsIpMigrator 
I — HsUebalizer 
I — HsUrchin 
I — HsMiva 

I — HsPerl  — HsAUStats  --  HsStats 
I 

I— HsPHP 

I—  HsUebShell 
I — Hs Os Commerce 
I—  HsPhpBB 
I — HsEasyAppSvc 
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Win  box  Directory  Structure 

Parallels  H-Sphere  Winbox  installation  creates  three  major  directories: 

■ HSphere 

■ HShome 

■ HSIogfiles 


In  this  section: 


HSphere 239 

HShome 240 

HSIogfiles 241 


HSphere 

HSphere  directory  includes  the  following  system  files: 

■ bin  - Parallels  H-Sphere  binary  files 

■ ftproot  - new  ftp  root  for  the  default  FTP  site; 

■ logs  - Parallels  H-Sphere  log  files  that  can  be  found  in  the  hsdirMogs  directory, 
(hsdir  is  the  directory  where  Parallels  H-Sphere  is  installed,  e.g:  C:\HSphere); 

■ scripts  - Parallels  H-Sphere  asp  scripts  files  and  configuration  file  (conf.inc); 

■ skeleton  - skeletons  for  websites  and  third  party  products; 

■ stats  - service  directory  for  stats  process; 

■ wawrapper  - service  for  wawrapper  process. 

Also  the  "cfg"  virtual  directory  is  created  on  the  web  site  which  was  selected  as  an 
Parallels  H-Sphere  website  during  the  installation.  This  directory  points  to  the  "scripts" 
physical  directory. 


Note:  Please  do  not  change  the  "cfg"  directory  configuration.  If  any  anything  is 
changed,  corresponding  config  parameters  must  be  updated  in  the  conf.inc  file,  and 
Parallels  H-Sphere  service  HSSvc  must  be  restarted. 


For  proper  work,  Parallels  H-Sphere  needs  several  parameters  listed  in  the  Parallels  H- 
Sphere  configuration  file  hsdir\scripts\conf . inc,  such  as: 

■ NetBios  machine  name  ("domainName"  variable); 

■ network  adapter  MAC  address  ("addressMAC"  variable); 

■ users'  home  directory  ("usersHome"  variable); 

■ HTTP  and  FTP  logs  directory  ("logPath"  variable); 
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■ MSSQL  server  name,  login,  password,  etc. 

Note:  when  updating  from  version  2.5  or  3.0  to  version  3.1  and  up,  the  HSphere 
directory  is  automatically  Created  at  C : \ Program  Files \HSphere. 


HShome 

The  location  of  home  directory  depends  on  the  type  of  Winbox  installation: 

■ fresh  installation  - Winbox  directory  is  installed  to  the  path  specified  in  a 
corresponding  Physical  server  profile.  If  it  is  not  set  there,  Parallels  H-Sphere 
Winbox  installer  will  automatically  create  it  on  NTFS  partition  with  the  largest  free 
space. 

■ manual  installation  - Winbox  directory  is  created  at  the  location  you  specify  in  a 
corresponding  step  of  the  Winbox  server  installtion  by  means  of  bundles 

HShome  directory  contains  all  user  homes.  Each  home  directory  has  account  owner's 
name.  A typical  user  home  has  the  following  directories: 

logs 

domainl . com 
domain2 . com 

domainN . com 

Each  domain  directory  has  content  similar  to  the  following: 

cgi-bin 

dirl 

dir2 

dirN 


logs  directory  would  have  subdirectories  for  each  domain: 

domainl . com  - (log  files  in  exYYMMDDHH.log  W3SVC  format) 

domain2  . com  - (-//-) 


domainN . com  - (-//-) 

Note  that  cgi-bin  is  not  a required  directory  in  the  site  structure  and  depends  on 
whether  the  cgi  directory  resource  is  enabled  for  the  site.  The  same  is  true  of  log  files 
for  individual  sites,  since  Parallels  Pi-Sphere  has  the  transfer  log  resource  that  allows 
users  to  access  log  files  for  their  site(s). 
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HSIogfiles 

HSiogf  iles  directory  includes  HTTP  and  FTP  logs  for  all  users.  It  is  a common 
directory  which  is  located  aside  from  log  directories  in  user  homes.  You  can  set  a 
location  of  this  directory  during  the  Parallels  H-Sphere  Winbox  installation.  Typically,  it 
is  located  in  the  disk  root  directory  (<drive>:  \hsiogfiies)  and  has  the  following 
content  structure: 

hslogf iles 

I 

I -WWW  (HTTP  logs) 

| | — W3SVC1  - (log  files  for  1 site  in  exYYMMDDHH.log  W3SVC  format) 

j | W3SVC2  - (-//-) 

j W3SVCn  - (-//-) 

I 

-ftp  (FTP  logs) 

I — msftpsvci  - (log  files  for  1 site  in  exYYMMDDHH.log  W3SVC  format) 

| MSFTPSVC2  - (-//-) 

MSFTPSVCn  - (-//-) 


Restarting  Winbox  Service 

To  stop  Parallels  H-Sphere  service  on  an  Parallels  H-Sphere  Windows  server,  run  in 
command  prompt: 

net  stop  hssvc 
net  stop  hsphere 

Here,  hssvc  is  required  for  ASP-based  Winbox  services  implemented  in  earlier 
versions  of  Parallels  H-Sphere  (written  in  C),  and  hsphere  for  SOAP-based  Parallels 
H-Sphere  services  (written  in  .NET). 

To  start  Parallels  H-Sphere  service  on  a Winbox,  run: 

net  start  hssvc 
net  start  hsphere 
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Restarting  IIS 

To  restart  IIS  on  an  Parallels  H-Sphere  Windows  server,  run  in  command  prompt: 

iisreset  /stop 
iisreset  /start 

Or,  simply: 

iisreset  /restart 


Enabling  Winbox  Shared  SSL 

SStarting  with  WINDOWS  2003  SP1,  IIS  6.0  supports  host  headers  in  SSL  bindings 
(http://www.microsoft.com/technet/prodtechnolAA/indowsServer2003/Library/IIS/596b91 

08-bl  a7-494d-885d-f8941  b07554c.mspx?mfr=true). 

Requirements:  Windows  2003  with  SP1  or  Windows  2000  server;  Parallels  H-Sphere 
3.0  Final 

This  document  covers  Winbox  Shared  SSL  integration  and  update. 


In  this  section: 


Integrating  Winbox  Shared  SSL 243 

Updating  Winbox  Shared  SSL 244 
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Integrating  Winbox  Shared  SSL 

There  are  two  different  approaches  to  integration  of  Winbox  Shared  SSL  implemented 
for  IIS  5.0  and  for  IIS  6.0: 

IIS  5.0 

On  IIS  5.0  service,  shared  SSL  virtual  hosts  are  still  used  but  their  purpose  has  been 
changed  to  act  as  certificate  holders.  IIS  5.0  uses  the  virtual  host  with  enabled  Shared 
SSL  for  certain  IP  to  establish  any  SSL  connections  for  this  IP  regardless  of  actual 
target  virtual  host.  So,  in  situations  when  a user  turns  shared  SSL  off  on  some  virtual 
host  which  was  the  first  shared  SSL  host,  the  others  shared  SSL's  on  this  IP  become 
unavailable.  In  other  words,  shared  SSL  virtual  hosts  on  IIS  5.0  are  intended  to  avoid 
such  issues. 

Admin  shared  SSL  creation: 

■ Post  the  certificate  and  key  on  the  server.  The  name  of  key  container  is 

{ 37 16B9D2-2  4 8 6-4  4 6a-928l-E4DlCA03ECOA}_<w/7of-carof  domain  name> 

■ Create  shared  SSL  service  virtual  host.  It  has  server  binding  formed  as 

<IP>:  80:  <IP>. sharedSSL2  where  IP  is  an  IP  address  of  this  particular  shared  SSL. 
Also  it  has  secure  binding  and  appropriate  wild-card  certificate  installed.  The  host 
number  of  such  virtual  host  will  be  in  the  range  10000-20000. 

User  shared  SSL  creation: 

■ SSL  with  appropriate  shared  SSL  certificate  is  enabled  for  customer's  virtual  host 

■ The  following  bindings  are  added  to  ServerBindings?  of  customer's  virtual  host: 

<IP> : 80 : <domain  alias>  and  <IP> : 443 : <domain  alias>  where  domain  alias  is  a 3rd 
level  domain  alias  for  customer  shared  SSL. 

IIS  6.0 


Shared  SSL  service  virtual  hosts  are  not  used  anymore. 

Admin  shared  SSL  creation: 

■ Post  certificate  and  key  to  the  server.  The  name  of  key  container  is  {3716B9D2- 
2486-446a-9281-E4DlCA03EC0A}_<  wild -card  domain  name> 

User  shared  SSL  creation: 

■ Enable  SSL  with  appropriate  shared  SSL  certificate  for  customer's  virtual  host 

■ Set  the  SecureBindings?  of  customer's  virtual  host  to  <IP> : 4 43 : <domain  alias> 
where  domain  alias  is  3rd  level  domain  alias  for  customer  shared  SSL. 
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Updating  Winbox  Shared  SSL 

If  there  is  shared  SSL  hosting  on  the  server  managed,  the  upgrade  procedure 
automatically  migrates  shared  SSL  to  a new  scheme.  It  detects  shared  SSL  by 
existence  of  virtual  hosts  with  Parallels  H-Sphere  shared  SSL  Log  plugin  log  plugin  and 
by  HKLM\ SOFTWARE \ Pso ft \HSphe re \SharedSSL \ Virtual  registry  key 
existence.  Before  performing  migration,  it  makes  IIS  metabase  backup  called 
sharedSSL  used  to  restore  metabase  if  something  goes  wrong.  Migration  procedure 
makes  the  following  changes: 

IIS  5.0 

Shared  SSL  service  virtual  host: 

■ removes  SharedSSL  ISAPI  filter 

■ renames  server  binding  from  <IP> : 80 : </P>. SharedSSL  to 
<IP> : 80  : <IP>  . SharedSSL2 

■ changes  log  plugin  to  standard  W3SVC 
removes  shared  SSL  virtual  directories  User  host: 

■ enables  SSL  with  appropriate  wild-card  certificate  for  customer's  virtual  host 

■ adds  <IP> : 8 0 : <domain  alias>  and  <IP> : 4 4 3 : <domain  alias>  bindings  to  server 
bindings,  where  domain  alias  is  a 3rd  level  domain  alias  for  customer  shared  SSL 

IIS  6.0 


Shared  SSL  service  virtual  hosts  are  removed. 

User  host: 

■ enables  SSL  with  appropriate  wild-card  certificate  for  customer's  virtual  host 

■ sets  secure  binding  to  <IP> : 443 : <domain  alias>  where  "domain  alias"  is  3rd  level 
domain  alias  for  customer  shared  SSL 
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Win  box  Statistics 


Parallels  H-Sphere  Winbox  has  the  following  log  plugins  installed: 

1 Parallels  H-Sphere  Web  Log  plugin:  a standard  log  plugin  for  virtual 
host  designed  to  calculate  statistics  info  only.  Besides,  for  a particular 
site  it  generates  HTTP  log  files  similar  to  W3C  log  format  files  in  the 
site's  log  directory. 

2 Parallels  H-Sphere  Web  Transfer  Log  plugin:  can  work  instead  of 
the  Web  Log  plugin.  It  also  implements  the  transfer  log  and  AWStats 
log  generating  functionality  beyond  the  standard  behavior. 

3 Parallels  H-Sphere  Shared  SSL  Log  plugin:  used  only  on  shared 
SSL  sites. 

4 Parallels  H-Sphere  Guest  FTP  Log  plugin:  installed  on  the  default 
FTP  host  to  collect  FTP  statistics  on  account  basis. 

5 Parallels  H-Sphere  FTP  Log  plugin:  installed  on  each  anonymous 
FTP  site  to  collect  FTP  statistics  on  FTP  site  basis. 

Please  mind  the  restrictions  common  to  all  Parallels  H-Sphere  log  plugins: 

1 All  log  files  are  rotated  daily  and  there  is  no  way  to  change  this 
rotation  period. 

2 Log  format  settings  can't  be  changed  for  Parallels  H-Sphere  log 
plugins. 

In  this  section: 
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Statistics  Modules 

Services.Stats.dll 


Location:  . . .\HSphere.NET\bin\services\Services.Stats.dll 

When  HSphere . exe  starts,  it  initializes  Service.Stats.dll , a timer  which  invokes  two 

threads  daily  at  00:01  AM: 

1 rotates  logs  (W3SVC,  W3FTP)  in  . . . \hslogf iles\,  analyzes  every 
log  file  and,  if  a log  was  created  more  than  a month  ago,  moves  that 
file  to  the  archive  of  log  files  for  that  month.  Archives  are  never 
rotated; 

2 collects  Webalizer  statistics; 

3 collects  AWstats  statistics; 

4 cleanses  log  files  in  the  users  home's. 
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Stats.exe 


Location:  . . .\HSphere\bin\stats.exe. 

Stats.exe  normally  runs  daily  at  00:01  AM.  However,  if  HSphere.exe  is  restarted 
between  00:00  AM  and  06:00  AM,  Stats.exe  will  start  together  with  Parallels  H- 
Sphere.exe;  the  next  day  Stats.exe  will  run  at  00:01  as  usual. 

Stats.exe  does  the  following: 

1 Executes  wawrapper.exe  and  awstats_updateall.pl; 

2 Rotates  the  user's  log  files  in  the 

. . .\home\<account_name>\log\<domain_name>  directories.  All  log  files 
created  more  then  a week  ago  will  be  deleted. 

WaWrapper.exe 

Location:  . . .\HSphere\bin\wawrapper.exe. 

WaWrapper.exe  analyzes  the  webalizer . current  files  for  each  domain. 

If  the  webalizer . current  file  is  not  corrupted,  WaWrapper.exe  creates  a backup 
copy  of  it  in  the  . . . \HSphere\wawrapper  directory  and  names  it  by  the  name  of  the 
domain  where  the  webalizer . current  resides. 


If  the  webalizer . current  file  is  corrupted,  wawrapper.exe  deletes  it  and  restores 
the  backup  copy  from  . . . \HSphere\wawrapper  directory. 

Then,  it  copies  the  files  hostslist.txt,  webalizer . conf , Webalizer  . exe  to  the 
temp  directory  and  executes  Webalizer.exe  for  each  group  of  records  from  the 

hostslist . txt  file. 


Webalizer  is  a third-party  product  installed  apart  of  Parallels  H-Sphere.  Its  target 
location  is  specified  by  customer  during  installation. 

The  number  of  records  in  each  group  is  set  by  default  to  l.  You  can  change  this  value 
by  adding  the  HostsinPackage  parameter  to  the  registry  key 

HKE Y_LOCAL_MACH INE\ SOFTWARE \Psoft\HSphe re \WaWrapper.  The 
HostsinPackage  value  is  unsigned  integer. 

Wawrapper.exe  monitors  Webalizer's  read/write  operations.  If  a period  between 
read/write  operations  is  greater  than  timeout,  WaWrapper  kills  this  webalizer  process 
and  all  records  in  this  group  adds  to  the  . . . \webaiizer\errhostsiist . txt  file. 

The  default  timeout  is  60  seconds.  You  can  change  this  value  by  adding  the  Timeout 
parameter  to  the  registry  key 

HKE Y_LOCAL_MACH INE \ SOFTWARE \Psoft\HSphe re \ WaWrapper.  The  Timeout 
value  is  unsigned  integer,  in  seconds. 

If  Webalizer.exe  returns  an  error  code  other  than  0,  all  records  in  a group  will  be  added 

to  errhostslist.txt. 
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Important:  With  lots  of  statistics,  it  may  take  up  to  several  days  or  even  weeks  for 
Webalizer.exe  to  process  it.  In  such  cases,  some  of  the  statistics  may  be  lost. 


Awstats_updateall.pl 

Location:  . . . \HSphere\skeleton\AWStats\tools\awstats_updateall  .pi 

awstats_updateall.pl  is  an  AWStats  tool  for  automatic  statistics  processing  on  all 
domains  for  which  the  AWStats  resource  is  turned  on  in  CP.  AWStats  automatically 
rotates  the  processed  records  to  the  awstats . log  files  in  domain  log  directories. 

Module  Log  Files 

Services.StatS.dll:  . . .\HSphere\log\services\stats\stats.log 
Stats.exe:  . . . \HSphere\logs\stats\*  . * 

WaWrapper.exe:  . . . \HSphere\logs\wawrapper\* . * 

AwstatS_updateall.pl:  . . .\HSphere\skeleton\AWStats\common.log 


Setting  Up  SharePoint  to  Use  MSSQL 
Server 


This  document  gives  you  information  on  how  to  install  Microsoft  Windows  SharePoint 
Services  on  your  Windows  2003  web  servers. 

According  to  Microsoft 

(http://www.microsoft.com/windowsserver2003/technoloqies/sharepoint/default.mspx), 

Windows  SharePoint  Services  technology  "is  an  integrated  portfolio  of  collaboration 
and  communication  services  designed  to  connect  people,  information,  processes,  and 
systems  both  within  and  beyond  the  organizational  firewall.  SharePoint  sites  provide  a 
central  repository  for  documents,  information,  and  ideas,  and  enable  users  to  work 
interactively  with  these  items." 

Currently  we  support  Windows  SharePoint  Services  v2  with  Service  Pack  2, 
http://www.microsoft.com/downloads/details.aspx?FamilylD=3144b72b-b4f2-46da- 

b4b6-c5d7485f2b42&DisplavLanq=en. 

In  this  section: 


Preinstallation  Requirements 248 

Installing  and  Configuring  SharePoint 249 
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Preinstallation  Requirements 

Before  you  install  Microsoft  Windows  SharePoint  Services  on  your  Web  server,  make 
sure  that  you  have  installed  the  required  hardware  and  software. 


Required 

Details 

Important:  SharedPoint  and  MSSQL  should  be  installed  on  one  and  same 
physical  server. 


Server  Hardware 

■ Intel  Pentium  III  (and  later)  compatible 
processor 

■ CPU/550  MHZ  1 CPU  (2  recommended) 

■ 512  MB  RAM 

Operation  System 

Microsoft  Windows  Server  2003: 

■ Standard  Edition 

■ Enterprise  Edition 

■ Datacenter  Edition 

Server  Software 
(Web  application 
server) 

■ NTFS  file  system 

■ Microsoft  ASP.NET 

■ Internet  Information  Services  in  IIS  6.0  worker  process 
isolation  mode  with  the  SMTP  service 

Server  Databases* 

■ Microsoft  SQL  Server  2000  Service  Pack  3 or  later 

■ Microsoft  SQL  Server  2005 

Browser  Client 

■ Microsoft  Internet  Explorer  5.01  or  later 

■ Microsoft  Internet  Explorer  5.5  or  later 

■ Netscape  Navigator  version  6.2  or  later 

■ Mozilla  1 .4  or  later 

* Microsoft  Windows  SharePoint  Services  SQL  Server  2000  Desktop  Engine  (WMSDE) 

is  not  supported  by  Parallels  H-Sphere. 
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Installing  and  Configuring  SharePoint 

To  install  and  configure  SharePoint  Services,  follow  the  procedure  below. 


In  this  section: 


Step  1.  Installing  MSSQL  Server 249 

Step  2.  Selecting  Authentication  Mode  for  SQL  Server 249 

Step  3.  Installing  SharePoint 250 

Step  4.  Configure  Parallels  H-Sphere  to  Use  SharePoint 251 


Step  1.  Installing  MSSQL  Server 

Prior  to  installing  SharePoint,  you  need  to  install  MSSQL  Server.  You  can  chose 
between: 

■ MSSQL  Server  2000  (on  page  311) 

■ MSSQL  Server  2005  (on  page  312) 

Step  2.  Selecting  Authentication  Mode  for  SQL  Server 

In  order  to  allow  Windows  SharePoint  Services  to  connect  to  your  SQL  Server 
database,  it  is  recommended  that  you  configure  the  SQL  Server  database  to  use 
Windows  authentication. 

For  SQL  Server  2000: 

1 On  your  server  computer,  go  to  Start  ->  All  Programs  ->  Microsoft 
SQL  Server  ->  Enterprise  Manager. 

2 In  Enterprise  Manager,  click  the  plus  sign  (+)  next  to  Microsoft  SQL 
Servers. 

3 Click  the  plus  sign  (+)  next  to  the  SQL  ServerGroup. 

4 Right-click  the  SQL  Server  name,  and  go  to  Properties. 

5 In  the  Properties  dialog  box,  click  the  Security  tab. 

6 In  the  Authentication  section: 

■ If  you  want  use  the  MSSQL  Server  only  for  Microsoft  Windows  SharePoint 
Services,  select  only  Windows  Authentication  mode. 

■ If  you  want  use  the  MSSQL  Server  both  for  Microsoft  Windows  SharePoint 
Services  and  hosting,  select  SQL  Server  and  Windows  Authentication 
mode. 

7 Click  OK. 


Note:  If  you  have  used  a domain  account  that  does  not  already  have  database  creation 
rights  in  SQL  Server,  you  can  give  the  account  this  access  using  Enterprise  Manager  in 
SQL  Server  2000,  as  a temporary  solution. 
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For  SQL  Server  2005: 

1 On  your  server  computer,  go  to  Start  ->  All  Programs  ->  Microsoft 
SQL  Server  2005  ->  SQL  Server  Management  Studio. 

2 On  the  Connect  to  Server  screen,  select  the  name  of  the  local  server 
from  the  Server  name  drop-down  list. 

3 On  the  Server  Properties  - Server  name  screen,  click  Security  in  the 
Select  a page  section. 

4 In  the  Server  Authentication  section: 

■ If  you  want  use  the  MSSQL  Server  only  for  Microsoft  Windows  SharePoint 
Services,  select  only  Windows  Authentication  mode. 

■ If  you  want  use  the  MSSQL  Server  both  for  Microsoft  Windows  SharePoint 
Services  and  hosting,  select  SQL  Server  and  Windows  Authentication 
mode. 

5 Click  OK. 


Note:  If  you  have  used  a domain  account  that  does  not  already  have  database  creation 
rights  in  SQL  Server,  you  can  give  the  account  this  access  using  SQL  Server 
Management  Studio,  as  a temporary  solution. 


Step  3.  Installing  SharePoint 

By  default,  when  you  install  Windows  SharePoint  Services,  the  Setup  program  installs 
WMSDE  (Microsoft  Windows  SharePoint  Services  SQL  Server  Desktop  Engine). 
Parallels  H-Sphere  does  not  support  WMSDE.  To  use  SharePoint  with  SQL  Server, 
run  Setup  with  the  Server  Farm  option.  Server  Farm  option  allows  supporting  a 
larger  set  of  Web  sites. 

1 Download  and  install  SharePoint: 
http://www.microsoft.com/windowsserver2003/technoloqies/sharepoint 

/default.mspx 

WARNING:  During  SharePoint  setup,  you  may  get  the  error  when  connecting  to 
http://localhost:SharePointPort/.  To  solve  it,  you  should  remove  the  string  cidentity 

impersonate="true"  />  from  C:\Program  Files\Common  Files\Microsoft 
Shared\Web  Server 

Extensions  \ 60  \ tempi  at  e\admin\  1033  \web  . con  fig.  Also  please  check  the 
Authentication  Methods  for  SharePoint  Central  Administration  WebSite  in  IIS.  And  if 
Basic  authentication  is  disabled,  enable  it. 

2 Go  to  SharePoint  Central  Administration: 

Start /Settings /Control  Panel/ Administrative 
Tools/SharePoint  Central  Administration 

3 Configure  Administrative  Virtual  Server  in  the  Server  Configuration 
tab: 

■ Select  Use  an  existing  application  pool  and  chose  StsAdminAppPool 
• Go  to  Security  Configuration  and  select  NTLM 
- Click  OK 
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4 Configure  Database  Server  in  the  Server  Configuration  tab: 

■ Select  Database  Server  and  enter  your  MSSQL  Server  IP  or  MSSQL  instance 

■ In  SQL  Server  database  name  enter  your  SharePoint  Main  DB  NAME 

■ Set  Windows  authentication 

5 In  Active  Directory  Account  Creation  choose  Users  already  have 
domain  accounts.  Do  not  create  active  directory  accounts. 

6 Click  OK 

Step  4.  Configure  Parallels  H-Sphere  to  Use  SharePoint 

1 If  you  installed  Microsoft  Windows  SharePoint  Services  after  Parallels 
H-Sphere  is  updated,  run  the  Parallels  H-Sphere  updater  again. 

2 Open  HSphere  . conf  ig  file  usually  located  in  the 

■ in  the  {disk} \Hsphere  .NET\bin\  directory  (for  H-Sphere  3.0  branch) 

■ in  the  {disk}\Program  Fiies\HSphere\Conf ig\  directory  (for  H-Sphere 
3. 1 and  up) 

and  make  sure  the  correct  name  of  your  MSSQL  server  was  set  in  the 
SharePoint  resource  setting  during  Parallels  H-Sphere  update. 

3 Restart  Parallels  H-Sphere  service: 

net  stop  hsphere 
net  start  hsphere 


Adding  ODBC  Resource 

This  document  explains  how  to  add  your  own  ODBC  drivers  to  Parallels  H-Sphere 
Winbox.  Please  contact  us  if  this  document  doesn't  work  for  your  version  of  Parallels  H- 
Sphere. 


In  this  section: 


Interface 252 

Configuration 255 
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Interface 

The  following  scripts  are  used: 

■ odbc-getdrivers . asp 

■ odbc-getparams . asp 

■ odbc-createdatasrc . asp 

■ odbc-updatedatasrc . asp 

■ odbc-deletedatasrc . asp 

In  this  section: 


odbc-getdrivers. asp 252 

odbc-getparams. asp 253 

odbc-createdatasrc.asp 253 

odbc-updatedatasrc.asp 254 

odbc-deletedatasrc.asp 254 


odbc-getdrivers.asp 

description:  returns  a list  of  available  ODBC  divers 

parameters: 

none 

return  value: 

successful  - 0 <list  of  driver  names> 
fail  - error  message 

comments: 


script  returns  the  list  of  drivers  that  are  both  installed  on  the  box  and  supported  by 
Parallels  H-Sphere  2.x  (they  are  registered  in  ODBCIniFile). 
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odbc-getparams.asp 

description: 

returns  a list  of  addmissible  attributes  for  this  ODBC  driver 
both  methods  "GET"  and  "POST"  are  supported 

parameters: 
driver  - driver  name 

return  value: 

successful  - 0<list  of  admissible  driver  attributes> 
fail  - error  message 

comments: 

every  parameter  has  the  following  format: 

<attribute  name>  \ <type>  \ <default 

value>  | <description>  | [Cvaluel  [ ; value2  [ ; value3  . . . ] 

See  below  for  details  on  this  format. 

odbc-createdatasrc.asp 

description: 

creates  new  data  source 

only  "POST"  method  is  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source 
user-name  - user's  accout  name 

<list  of  admissible  attributes  of  this  ODBC  driver  and  their  values> 
return  value: 

successful  - 0 
fail  - error  message 


comments: 
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1)  all  attributes  with  empty  values  are  ignored; 

2)  all  attributes  with  a type  path  (see  below)  get  a path  to  user's  homedir,  but  the 
existence  of  this  path  is  not  verified 

3)  data  source  name  is  created  according  to  the  pattern:  user-name  + DSN 

odbc-updatedatasrc.asp 

description: 

updates  parameters  of  the  existing  data  source 
only  "POST"  method  is  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source 
user-name  - user's  accout  name 

<list  of  admissible  attributes  of  this  ODBC  driver  and  their  values> 

return  value: 

successful  - 0 

fail  - error  message 

comments: 

default  values  are  set  for  attributes  that  have  not  been  specified  or  have  empty  values, 
all  comments  to  data  source  creation  are  also  true  of  data  source  update. 

odbc-deletedatasrc.asp 

description: 

deletes  existing  data  source. 

both  "GET"  and  "POST"  methods  are  supported 

parameters: 

driver-name 

DSN  - name  of  the  new  data  source. 


user-name  - user's  accout  name 
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return  value: 

successful  - 0 
fail  - error  message 
comments: 
no  comments 

Configuration 

To  configure  ODBC  use  a file  of  the  below  format.  Full  path  to  this  file  is  registered  in 
conf.inc  (the  "ODBCIniFile"  variable).  By  default  it  is  called  "odbcdrv.ini"  and  sits  in  the 
directory  with  ASP  scripts. 

This  file  has  a usual  windows  .ini  file  format,  i.e.  is  broken  into  sections  with  headings 
enclosed  in  square  brackets.  Every  section  corresponds  to  an  ODBC  driver,  its  name 
being  the  heading  of  the  section.  The  body  of  the  section  includes  driver  attributes  in 
the  following  format: 

<attribute  name>=<type>  | <default  value>  | <description>  | [cvaluel  [ ; value2  [ ; value3  . . . ] 
where: 

■ <attribute  name>  - name  of  the  ODBC  driver  attribute  (e.g.  DBC) 

■ <type>  - typically  a string  of  the  type:  <typeid>_[required|optinal],  where  typeid  is 
the  name  of  the  type,  e.g.  "string",  that  can  be  required  or  optional  depending  on  the 
parameter.  Can  take  the  following  values: 

path_required  - required  path  (an  individual  path  type  is  required  to  identify 
relative  path  to  userhome  dir) 

path_optionai  - optional  path 

string  required  - required  string 

string_optionai  - optional  string 

string_password  - password 

integer_required  - mandatory  integer  value 

integer_optionai  - optional  integer  value 

seiect_required  - mandatory  list  of  values 

seiect_optionai  - optional  list  of  values 

trigger  - radio-button  switch 

■ <default  value>  - default  value  for  the  given  attribute;  a space  if  missing  (NOT  AN 
EMPTY  STRING!) 

■ <description>  - attribute  description 

■ cvaluel  [ ; vaiue2  [ ; vaiue3 ...  - values  for  the  list;  must  be  filled  only  for  the 
'select'  types.  Use  semicolon  (;)  as  delimiter. 
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To  add  a new  ODBC  driver  to  the  ODBCIniFile,  add  a new  section  with  the  heading 
identical  to  the  name  of  the  driver  and  the  attributes  that  are  described  according  to  the 
above  rules. 

Note:  When  a user  enables  an  ODBC  resource,  Parallels  H-Sphere  lists  drivers  that 
can  be  found  both  among  those  installed  on  the  server  and  those  in  the  odbcdrv.ini  file. 
The  obcdrv.ini  file  contains: 

■ [Microsoft  Paradox  Driver  (*.db  )] 

■ [Microsoft  Access  Driver  f.mdb)] 

■ [Microsoft  Visual  FoxPro  Driver] 

■ [Microsoft  dBase  Driver  (*.dbf)] 

■ [Microsoft  Excel  Driver  (*.xls)] 

■ [SQL  Server] 

■ [MySQL] 

• [MySQL  ODBC  3.51  Driver] 

■ [PostgreSQL] 
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Configuring  ColdFusion 

ColdFusion  includes  a server  and  a development  toolset  designed  to  integrate 
databases  and  Web  pages.  With  ColdFusion  Fusion,  a user  can  enter  a zip  code  on  a 
Web  page,  and  the  server  would  query  a database  and  present  the  results  in  the  FITML 
form. 

For  extensive  coverage  of  ColdFusion,  please  refer  to 
http://www.macromedia.com/software/. 


WARNING:  We  currently  don't  recommend  updating  Parallels  H-Sphere  to  version  2.5 
and  up  when  there  are  512  and  more  ColdFusion  mappings  on  a Windows  server  (i.e., 
ColdFusion  is  turned  on  for  more  than  51 1 Winbox  users)! 


> To  configure  ColdFusion  for  Parallels  H-Sphere: 

1 Buy  ColdFusion  license  package. 

2 Install  ColdFusion  on  your  Windows  box  following  the  directions  of  the 
Wizard.  (Parallels  H-Sphere  2.5  and  up  supports  6.0,  6.1  and  7.0 
ColdFusion  versions). 

3 Install  latest  Parallels  H-Sphere  Winbox  3.1  Beta  2 or  higher. 


When  performing  the  step-by-step  installation  procedure,  set  also  ColdFusion 
admin  password  via  the  interface  after  a logical  win  server  have  been  added.  To  do 
this,  Go  to  E.  Manager  ->  Servers  - > L.Servers  and  click  the  logical  win  server  name. 
Enter  the  password  in  the  Additional  options  section  and  click  Set: 


Password  of  ColdFusion 
administrator 


|l098ght73 


You  may  also  install  ColdFusion  on  a ready  Parallels  H-Sphere  3.1  Beta  2 and  higher 
Winbox.  For  this,  do  the  following: 

1 Perform  steps  1 and  2 described  above. 

2 Enter  ColdFusion  admin  password  via  the  interface. 

3 Run  Parallels  H-Sphere  Update  Wizard. 
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Enabling  ASP.NET  2.0 

Parallels  H-Sphere  uses  some  of  ASP.NET  features.  That's  why  ASP.NET  should 
already  be  installed  before  installing  or  upgrading  Parallels  H-Sphere  on  a Winbox. 

It  is  possible  to  switch  between  ASP.NET  versions  in  user  CP. 

ASP.NET  requires  SOAP  enabled. 

> To  enable  ASP.NET  2.0  hosting  on  your  Parallels  H-Sphere  Winbox: 

1 Install  ASP.NET  Framework  2.0  according  to  the  installation 
instructions. 

2 In  the  command  line  type: 

%WinDir%\Microsof t . NET\Framework\2 . 0\aspnet  regiis.exe  -i 

where 

%winDir%  is  a path  to  the  directory  where  Windows  is  installed  (usually  C:\WINNT) 
%version%  is  a version  of  ASP.NET  (vl  .0.3705  or  later) 

3 Reconfigure  ASP.NET  resource  in  the  HSphere  . conf  ig  file  (usually, 

C:\HSphere.Net\bin\HSphere.config)  to  use  resource 
"aspnet2_0"  instead  of  "aspnetl  i".  For  this,  edit 
HSphere  . conf  ig  and  replace  the  line: 

Cresource  name="aspnet" 

type="Ps°ft .HSphere .Resources . IIS .AspNetl  1" 
location="Resources . IIS . ASPNET"  /> 

with  this  line: 

Cresource  name="aspnet" 

type="Psoft .HSphere .Resources . IIS .AspNet2  0" 
location="Resources . IIS .ASPNET"  /> 

4 Restart  Parallels  H-Sphere  Winbox  service  (on  page  241) 

5 Download  ASP.NET  Migration  Tool  from 
http://download.hsphere.parallels.com/shiv/WinBox/AspNetMiqr.exe, 

unpack  and  execute  this  tool  to  reconfigure  machine. config  with  the 
new  version  of  ASP.NET. 

For  example,  to  migrate  from  ASP.NET  1 .1  to  ASP.NET  2.0,  run  the  following 
command: 

aspnetmigrate  -from  1.1.4322.0  -to  2.0.50727.0 
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Moving  Log  Files 

This  document  explains  how  to  change  the  HSLOGFILES  directory  location  on  Winbox. 
This  may  be  required,  for  instance,  if  you  are  replacing  your  HDD. 

1 Link  the  new  HDD  to  the  old  HSLogs  location.  This  can  be  done  with 
Sysinternals  Junction 

(http://www.svsinternals.eom/ntw2k/source/misc.shtml#iunction)  or 

any  other  utility  of  this  kind. 

2 Copy  logs  into  the  'hslogf  iles'  directory  on  the  new  HDD. 

3 Set  new  path  to  the  'hslogfiles'  dir  in 
\hsphere \ script s \ conf . inc  and 
\HSphere. NET\bin\hsphere . conf ig. 

4 Restart  hsphere  services. 


Removing  Old  Log  Files 

User  log  files  are  stored  for  7 days  and  then  automatically  removed. 

> To  remove  old  log  files  manually: 

1 Go  to  the  HSphere \ scripts \ directory.  In  the  conf . inc  file  find 
the  directory  where  WWW  and  FTP  logs  are  stored. 

//  path  to  directory  where  websites  logs  are  located 
logWebPath  = "d  : \\HSlogf  ilesWwww" 

//  path  to  directory  where  ftpsites  logs  are  located 
logFtpPath  = "d:  \\HSlogfiles\\ftp" 

2 Go  to  the  respective  directory  (cd  d:\hslogfiies\www) 

Here  you  will  find  directories  containing  web  log  files  for  each  domain 
e.g.:  w3svci,  W3SVC2,  W3SVC3  and  so  on. 

or 

directories  containing  ftp  log  files  for  each  domain 
e.g.:  msftpi,  msftp2,  msftp3  and  so  on. 

3 Enter  "del  /s  /q  <mask>"  command  in  the  command  line  where 
<mask>  is  the  mask  for  the  files  to  be  removed. 

* You  can  use  a wildcard  in  the  mask. 

Names  of  the  log  files  have  the  following  appearance: 

exyymmddhh . log  or  just  exyymmddhh 


where 


ex  - the  essential  part  of  the  name 
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yy  - two-digit  year  value 
mm  - two-digit  month  value 
dd  - two-digit  day  value 
hh  - two-digit  hour  value 

Examples  of  how  to  use  the  del  command: 

del  /s  /q  exOi*  - removes  all  files  for  the  year  2001 

del  /s  /q  ex0i02*  - removes  all  files  for  February,  2001 

del  /s  /q  ex??02*  - removes  all  files  for  February  of  all  the  years 

? - Any  single  character 
* - Zero  or  more  characters 
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Moving  User  Homes 

This  document  explains  how  to  move  the  directory  for  user  homes  to  a different 
location.  This  may  be  required,  for  instance,  if  you  are  replacing  your  hard  drive  with  a 
bigger  one. 

Winbox  supports  only  one  directory  for  user  homes,  which  means  you  can't  add 
another  directory  for  user  homes  to  use  alongside  with  the  one  you  already  have. 

> To  change  HSHOME  directory: 

1 Add  new  HDD 

2 Create  new  HSHOME  directory 

3 Copy  all  user  content  into  the  new  HSHOME  directory  with  Xcopy.  For 
example,  to  copy  from  disk  D:  to  disk  F:,  execute  in  the  command 
prompt: 

Xcopy  d : \hshome  f : \hshome  /O/E 

4 Change  the  path  to  HSHOME  directory  in: 

■ Registry  key 

HKEY_LOCAL_MACHINE\SOFTWARE\Psof t\HSphere\HsServULayer \Quot 
aService\HomeDir 

■ [disk] : \hsphere\scripts\conf . inc 

■ [disk] : \hsphere . net\bin\hsphere . conf ig 

5 Restart  ail  Parallels  H-Sphere  services 

6 Link  the  new  HDD  to  the  old  home  dir  location.  This  can  be  done  with 
Sysinternals  Junction 

(http://download.hsphere.parallels.com/shiv/WinBox/linkmaqic.exe)  or 

any  other  utility  of  this  kind. 

7 Move  quota  entries  for  all  accounts  using  the  QuotaMove  utility 
(http://download.hsphere.parallels.com/shiv/WinBox/QuotaMove.exe). 

For  example,  to  move  quote  entries  from  disk  D:  to  disk  F:,  execute  in 
the  command  prompt: 

QuotaMove . exe  d : \ f : \ 


Maintaining  HShome 

This  document  explains  how  to  maintain  HShome  directory  on  Winbox  and  to  clean  it 
from  orphaned/redundant  folders  and  files.  Orphaned  user  files  are  redundant  files  that 
remain  after  deleting  Parallels  H-Sphere  users  from  database. 

HShome  maintenance  is  performed  with  help  of  the  hshome_cieanup . j s script  which 
also  informs  you  of  missing  user  home  folders  if  they  are  not  found. 
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> To  clean  HShome  from  orphaned  files: 

1 Download  and  unpack  the  hshome_cleanup  script  from 
http://download.hsphere.parallels.com/shiv/WinBox/hshome  cleanup.z 

ia- 

2 Run  the  script: 

cscript  hshome_cleanup . js  <userslistfile>  <hshome _path>  <orphaned _path>  [/f] 
Where: 

cscript  - script  interpreter 

<userslistfile>  - file  with  hsphere  users  list;  usernames  delimeted  by  CRLF.  Obtain  it 
by  running  the  following  query: 

select  login  from  unix  user  where  hostid=N;  [where  N is 
logical  server  ID] 

<hshome _path>  - location  of  HShome 

<orphaned_path>  - path  to  the  existing  folder  where  redundant  files/folders  will  be 
moved. 

[/f  ] : with  this  option  files  won't  be  moved  at  "hshome"  root.  As  an  example,  you 
will  run  something  like: 

cscript  hshome_cleanup . j s users.txt  d:\hshome  d:\hsorphaned 

As  the  result,  all  orphaned  files  will  be  moved  to  the  specified  directory. 

Here  is  an  example  of  script  execution: 

E:\>cscript  hshome  cleanup. js  users.txt  e:\hshome  e:\hsorphaned 
Microsoft  (R)  Windows  Script  Host  Version  5.6 

Copyright  (C)  Microsoft  Corporation  1996-2001.  All  rights  reserved. 
Users  list  file:  users.txt 
HSHome  location:  e:\hshome 
Orphaned  location:  E : \hsorphaned\ 

Moving  files... 

E:\hshome\l.reg...  Ok 

Warning!!!  Missing  user  folder(s)  found: 

User:  none 
User:  west 


Orphaned  folder (s)  found: 
Moving  folder  "testwil".. 

. Ok 

Moving 

folder 

"testwin" . . 

. Ok 

Moving 

folder 

"unixtest" . 

. . Ok 

Moving 

folder 

"userwind" . 

. . Ok 

Moving 

folder 

"vmwinl " . . . 

Ok 

Moving 

folder 

"win0422" . . 

. Ok 

Moving 

folder 

"win0425" . . 

. Ok 

Moving 

folder 

"winmiva4 " . 

. . Ok 

Moving 

folder 

"wintest" . . 

. Ok 

Moving 

folder 

"wintstOl" . 

. . Ok 

Moving 

folder 

"wmwinl " . . . 

Ok 

Finished 
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Changing  hsadmin  Login  and  Password 

Parallels  H-Sphere  control  panel  accesses  Windows  boxes  with  the  hsadmin  user. 

> To  change  the  hsadmin  login  and  password: 

1 Generate  a new  password  hash  using  the  following  tool: 
http://download.hsphere.parallels.com/shiv/WinBox/HashGenerator.zip 

In  cmd  window,  run: 

> HashGenerator.exe  "password" 

2 Put  the  new  hash  to  the  following  line  in  the 

[disk]:  \H  Sphere  . NET\bin\hsphere  .config  file: 

"prop  name="password"  value="new  HASH"  description="Parallels 
H-Sphere  user  password" 

3 Restart  Parallels  H-Sphere  services  and  change  the  password  on  your 
administrator  control  panel  for  the  Windows  physical  server. 


Winbox  IP  Migration 

This  section  explains  how  to  migrate  a pool  of  IPs  on  Parallels  H-Sphere  Winbox, 
including  physical  server  IPs,  logical  server  IPs,  and  user  dedicated  IPs.  It  is  important 
that  Parallels  H-Sphere  Winbox  software  is  working  correctly  at  the  time  of  migration. 


In  this  section: 


Step  1 . Bind  Target  IPs  on  Winbox 264 

Step  2.  Add  Double  Bindings  on  IIS 264 

Step  3.  Create  Migration  XML 265 

Step  4.  Run  the  Migration 265 

Step  5.  Remove  Old  IP  Bindings  on  IIS 266 
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Step  1 . Bind  Target  IPs  on  Winbox 

Make  sure  all  the  target  IPs  are  up.  If  they  aren't  you  can  either  bind  them  manually  or 
use  the  following  steps: 

1 Create  a file  named,  for  instance,  target_ips.txt  with  the  list  of  IPs  and 
masks  to  bind,  as  follows: 

<IPl>  <netmask> 

<IP2>  <netmask> 

<IPn>  <netmask> 

2 Download  IpCreator  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipcreator.exe. 

3 Run  the  IpCreator  utility: 

IpCreator.exe  target_ips.txt  > log.txt 


Step  2.  Add  Double  Bindings  on  IIS 

On  this  step,  we  will  duplicate  IP  bindings  for  virtual  web  hosts  on  IIS  to  use  old  and 
new  IP  bindings  simultaneously,  which  will  help  us  avoid  DNS  propagation  downtime. 

1 Create  a file  named,  for  instance,  ip_map.txt  with  space  separated  old 
and  new  IP  correspondences,  according  to  the  following  format: 


Cold 

IP1> 

Cnew 

IP1> 

Cold 

IP2> 

Cnew 

IP2> 

Cold 

IPn> 

Cnew 

IPn> 

2 Download  IpMigrator  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipmiqrator.exe. 

3 Run  the  IpMigrator  utility: 

ipmigrator . exe  ip_map . txt  > ipmigrator . log 


Note:  IpMigrator  inserts  new  bindings  AFTER  the  corresponding  old  bindings  in  the  IIS 
metabase.  Parallels  H-Sphere  uses  the  first  binding  to  obtain  virtual  web  host  name 
and  IP,  which  means,  while  the  old  bindings  exist  in  the  bindings  list,  Parallels  H- 
Sphere  will  manage  resources  with  the  old  IP.  For  instance,  Parallels  Pi-Sphere  will  add 
host  aliases  to  the  old  IP's.  Thus  it  is  strongly  recommended  to  remove  old  IP  bindings 
as  soon  as  they  are  not  needed. 
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Step  3.  Create  Migration  XML 

Create  file  ipmigration.xml  of  the  following  format  and  put  it  on  the  CP  server: 

<?xml  version=" 1 . 0 " ?> 

< ! DOCTYPE  ips  [ 

<! ELEMENT  ips  (ip+)> 

<! ELEMENT  ip  (#PCDATA)> 

< ! ATTLIST  ip  name  CDATA  #REQUIRED> 

< ! ATTLIST  ip  new_ip  CDATA  #REQUIRED> 

< ! ATTLIST  ip  new_mask  CDATA  " [New_NetMask] "> 

]> 

<ips> 

<!--  Delete  the  lines  with  IPs  you  don't  want  to  migrate!  --> 

<ip  name=" [Old  IP1]"  new  ip=" [New^IPl] "/> 

<ip  name=" [Old  IP2]"  new  ip=" [New^IP2] "/> 

<ip  name=" [01d_IP3] " new  ip=" [New_IP3] "/> 

<ip  name=" [01d_IP4 ] " new  ip=" [New_IP4 ] " new  mask=" [New  NetMask2]"/> 
</ips> 

You  can  find  more  information  on  ipmigration.xml  in  Changing  IPs  for  the  Parallels  hl- 
Sphere  Cluster  (on  page  40). 


Step  4.  Run  the  Migration 

1 Stop  Parallels  H-Sphere  (on  page  54) 

2 Execute  the  following  commands  one  by  one  on  the  CP  server. 

Replace  <LS_ID>  with  the  ID  of  the  Winbox  logical  server.  To  find  out 
the  ID  of  the  logical  server,  go  to  E. Manager  ->  L.Servers  in  Parallels  H- 
Sphere  admin  panel. 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  --ip- 
change  — lServerlds =<LSJD>  ipmigration.xml 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  -- 

recreate-zone  --lServerlds =<LSJD>  ipmigration.xml 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  -- 

service-zone  --lServerlds =<LSJD>  ipmigration.xml 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . IPMigratorFast  -- 

cus  tom-rec  — lServerlds =<LSJD>  ipmigration  . xml 

3 Start  Parallels  H-Sphere  (on  page  54) 
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Step  5.  Remove  Old  IP  Bindings  on  IIS 

At  this  point  in  time,  you  have  duplicate  bindings  of  new  and  old  IPs.  It  is  recommended 
that  you  remove  old  IP  bindings  as  soon  as  DNS  servers  across  the  world  refresh 
themselves  (usually  in  no  more  than  2 days). 

The  old  bindings  on  IIS  can  be  removed  with  the  IpChange  utility  (),  which  uses  the 
same  IP  map  file  as  the  IpMigrator  utility  (step  2 above). 

1 Download  IpChange  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/ipchanqe.exe 

2 Run  IpChange  utility: 

ipchange . exe  ip_map . txt  > ipchange . log 

3 Restart  Parallels  H-Sphere  (on  page  54). 
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Uninstalling  Winbox 

Parallels  H-Sphere  Windows  software  can  be  uninstalled  from  a Windows  server  only 
manually. 

> To  uninstall  Winbox: 

1 Go  to  the  directory  [disk]  : \Hsphere\bin\ 

■ Unregister  the  HSSVC  and  HsQuotas  services  by  running  the  commands: 

hssvc  /unregserver 
HsQuotas  /unregserver 

■ Remove  the  hkey_local_mach ine\  software \Pso ft  key  from  the  registry. 

2 Remove  the  hsphere  service  by  running  in  the  command  line: 

[WinDir] \Microsof t . NET\Framework\ [version] \InstallUtil . exe  /u 
[ \hsphere . net] \bin\hsphere . exe 

Where: 

■ [WinDir]  is  a path  to  the  directory  where  Windows  is  installed  (usually 

C : \Windows) 

■ [version]  is  a version  of  ASP.NET  (vl  .0.3705  or  later) 

[\hsphere.net]  is  a path  to  the  directory  where  HSphere.NET  is  located  For 
example: 

C : \Windows\Microsof t . NET\Framework\vl . 1 . 4322\InstallUtil . exe 
/u  C : \hsphere . net\bin\hsphere . exe 

3 Go  to  the  IIS  interface  ( Programs  ->  Administrative  Tools  ->  Computer 
management  ->  Internet  Information  Services)  and  perform  one  of  the 
following  two  actions: 

■ If  Parallels  H-Sphere  was  set  up  on  the  default  website,  remove  the  CFG, 

Urchin,  Webshell  and  MS  SQL  virtual  directories; 

■ If  Parallels  H-Sphere  was  set  up  on  a separate  website,  remove  the  website. 

4 Check  in  the  component  services  on  the  Parallels  Fi-Sphere  website 
for  COM+  applications  cfg  and  cfg/net.  To  do  this: 

Go  to  Programs  ->  Administrative  Tools  ->  Component  Services  ->  My 
Computer  ->  COM+  Applications 

• Remove  1 1 S{  Default  Website  Root//cfg//NET}  and  1 1 S{  Default  Website  Root//cfg}. 
In  order  to  remove  them,  right-click  on  it  and  choose  Properties,  go  to  Advanced 
tab  and  uncheck  Disable  Deletion  option. 

5 In  the  IIS  interface  re-map  default  FTP  root  to  the  IIS  directory 
(usually  c:\inetpub\ftproot): 

■ Go  to  FTP  Sites,  right-click  the  Default  FTP  Site  ->  Properties. 

• On  the  page  that  appears  click  Properties,  then  browse  for  folder  and  choose 
ftproot  as  shows  below: 
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OK 
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6 Re-map  default  web  root  to  the  IIS  directory  (usually 

c : \ in et pub \ www root): 

■ Go  to  Web  Sites,  right-click  the  Default  Web  Site  ->  Properties. 

• On  the  page  that  appears  click  Properties,  then  browse  for  folder  and  choose 
wwwroot  as  shows  above  on  Step  5. 

7 Remove  the  user  that  was  created  during  the  Parallels  H-Sphere 
installation  to  administer  Parallels  H-Sphere  (by  default,  it's  user 
H Sad  min). 

8 Stop  IIS  service  by  running  in  the  command  line: 

iisreset/stop 

9 Remove  the  Parallels  H-Sphere  directories  from  their  location:  usually 

C:\Hsphere  and  C:\Hsphere.Net. 

10  Restart  IIS  service  by  running  in  the  command  line: 

iisreset 


Important:  do  not  delete  the  chsphere . net>  directory  if  it  contains  any  of  the 
packages  installed.  If  you  want  to  uninstall  Parallels  H-Sphere,  uninstall  all  Parallels  H- 
Sphere  packages  first. 


Winbox  Security  Scheme 
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Parallels  H-Sphere  introduces  a Winbox  security  scheme.  The  goal  of  the  scheme  is  to 
get  rid  of  ' local  system  ' identity  for  application  pool  processes  of  IIS  6.0,  to 
simplify  some  tasks  such  as  managing  FrontPage  and  ASP.NET,  and  to  make  Parallels 
Pi-Sphere  accounts  hierarchy  more  structural. 


IMORTANT:  1 . The  Parallels  Pi-Sphere  version  with  the  security  scheme  does  not  work 
with  Serv-U  FTP  server. 

2.  For  the  security  scheme  to  be  operational,  make  sure  to  enable  SOAP. 


In  this  section: 


Accounts  Fiierarchy 270 

IIS  Security  Management 271 

NTFS  permissions 272 

FrontPage  Server  Extensions  Management  Notes 273 

ASP.NET  Management  Notes 273 

Migration  Notes 273 

Recovery  Notes 274 
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Accounts  Hierarchy 

Features: 

■ There  are  several  predefined  security  groups: 

■ hs_accts  - contains  all  accounts  created  by  Parallels  H-Sphere  on  this  server 

■ hs_ftp_accts  - contains  accounts  created  by  Parallels  H-Sphere  which  are 
used  as  FTP  logins  for  Parallels  H-Sphere  users 

■ hs_iusr_accts  - contains  accounts  which  are  used  as  anonymous  for 
Parallels  H-Sphere  virtual  hosts 

■ hs_ftp_subaccts  - contains  accounts  which  are  used  as  sub  FTP  logins 

■ During  creation  of  a user,  a special  group  is  being  created  named  as  <user 
name>_group.  This  group  contains  all  accounts  related  to  a particular  Parallels  H- 
Sphere  account,  such  as  FTP  login  account,  anonymous  accounts  for  every  virtual 
host  owned  by  this  user,  and  sub  FTP  logins  accounts. 

The  following  improvements  have  been  made  to  accounts  hierarchy: 

■ a subaccount  is  no  longer  a member  of  <main  accounOgroup 

■ <main  account*  subaccts  group  is  being  created  for  each  account  that  has 
subaccounts 

■ any  subaccount  of  a particular  account  becomes  a member  of  <main 
account*  subaccts  group 

■ NTFS  permissions  to  particular  subaccount  home  directory  are  given  explicitly  for 
this  subaccount  in  addition  to  existing  NTFS  permissions  for  this  directory 
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IIS  Security  Management 

Features: 

■ The  FTP  account  login  is  not  used  anymore  as  anonymous  web  access  for  all  sites 
owned  by  the  user.  Instead  of  this,  for  each  virtual  host  a separate  account  with 
random  password  is  being  created  during  virtual  host  creation  procedure. 

■ The  password  synchronization  IIS  feature  which  requries  'local  system' 
identity  for  web  application  process  is  not  used  anymore.  The  reason  for  this  is  that 
this  account  and  randomly  generated  password  is  registered  in  the  metabase  as 
anonymous  for  this  particular  virtual  host. 

■ An  account  is  being  added  to  hs_accts,  hs_iusr_accts  and  Parallels  H-Sphere 
account  group.  Each  anonymous  login  has  the  following  format: 

<IUSR_user  name>  <virtual  host  number>  where  <username>  is  Parallels  H-Sphere  FTP 
account  title  and  <virtual  host  number>  is  number  of  particular  virtual  web  host  owned 
by  this  Parallels  Pi-Sphere  account. 

■ Now  each  IIS  web  application  process  is  run  under  'network  service'  identity. 
There  is  a number  of  Parallels  Pi-Sphere  modules  run  in  IIS  web  processes  which 
should  perform  some  privileged  operations  such  as  read/write  files  or  register  keys 
protected  by  NTFS  permissions.  That  is  why  Parallels  Pi-Sphere  creates  a special 
'HsiSAPiAcct'  account  as  a member  of  the  'Local  Administrators'  group. 
This  account  is  used  by  Parallels  Pi-Sphere  IIS  modules  to  perform  such  privileged 
operations.  In  addition,  its  password  is  being  regenerated  each  time  IIS  is  started 
for  security  reason. 
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NTFS  permissions 

There  are  permission  schemes  which  are  used  for  Windows  2000,  Windows  2003,  and 
for  both  platforms. 

Windows  2000 

The  following  NTFS  permissions  are  set  for  a user  home  directory: 

■ Local  Administrator  group:  full  access 

■ SYSTEM:  full  access 

■ ASPNET  account:  read  access 

■ <FTP account name>  group  local  group:  modify, read,  write,  execute,  list 
FOLDER  CONTENT 


Windows  2003 

The  following  NTFS  permissions  are  set  for  a user  home  directory: 

■ Local  Administrator  group:  full  access 

■ SYSTEM:  FULL  ACCESS 

- NETWORK  SERVICE:  READ  access 

■ <FTP account name>  group  local  group:  modify, read,  write,  execute,  list 
FOLDER  CONTENT 

The  following  permissions  are  added  to  Parallels  H-Sphere  dir>b in  directory: 

■ NETWORK  SERVICE:  READ,  EXECUTE,  LIST  FOLDER  CONTENT 


Relevant  to  both  platforms 

The  following  NTFS  permissions  are  used  for  ODBC  DSN  registry  key: 

■ Local  Administrator  group:  full  access 

■ SYSTEM:  full  access 

■ <FTP account na/ne>_group  local  group:  query  value,  set  value,  create 
SUBKEY, ENUMERATE  SUBKEYS , NOTI FY 
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Frontpage  Server  Extensions  Management  Notes 

The  following  changes  were  made  to  FPSE  management  as  a part  of  a new  scheme: 

■ Anonymous  access  is  assigned  to  Browser  role  for  any  FPSE  enabled  virtual  host 

■ <FTP  account  name>_ group  local  group  is  set  as  FPSE  administrator  for  any  FPSE 
enabled  virtual  host 

■ FIsAuth  ISAPI  filter  is  no  more  used  for  FPSE  enabled  virtual  hosts 


ASP.NET  Management  Notes 

■ The  ASP.NET  management  operations,  which  enable  and  disable  ASP.NET 
service  for  a particular  virtual  web  host,  are  based  on  the  .NET  framework 
configuration  file  machine. config. 

■ The  following  fragment  is  added  to  the  machine. config  file  for  a particular  virtual 
host  if  ASP.NET  is  being  disabled  for  this  virtual  host: 

Clocation  path="<virtual  host  domain  name>" 
allowOverride=" f alse"> 

<system. web> 

<authorization> 

<deny  users="*"/> 

</authorization> 

</ system . web> 

</location>> 

■ When  ASP.NET  service  is  enabled  for  a particular  virtual  host,  it  is  being  removed 
from  machine  . config  file,  if  found. 


Migration  Notes 

■ During  the  Winbox  upgrade,  all  existing  accounts  will  be  automatically  migrated  to  a 
new  security  scheme.  This  process  migrates  account  settings,  web  settings,  NTFS 
permissions  for  home  directories  and  ODBC  DSNs,  ASP.NET  settings,  FPSE 
settings  and  can  take  significant  time. 

■ The  migration  procedure  is  performed  once.  If  it's  necessary  for  some  reason  to 
repeat  the  migration,  the  NewSecurity  line  should  be  removed  from  Parallels  H- 
Sphere.NET  dir>  bi  nins tall . history  file. 

■ Migration  process  can  be  monitored  using  migration  log  which  can  be  found  in  the 
update.log  log  file  of  upgrade  tool. 


Important:  during  the  migration,  IIS  servers  will  be  automatically  restarted  on  Windows 
2003. 
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Recovery  Notes 

To  perform  server  recovery  (on  page  447)  or  server  to  server  movement,  use  the 
SetScrtNs . exe  tool  which  is  a new  analogue  of  the  SetScrt . exe  tool.  It  has  the 
same  purpose  as  the  older  version,  but  sets  the  correct  permissions  for  a new  security 
scheme. 

Download  SetScrtNs  Tool: 

http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 


Migrating  Serv-U  to  MS-FTP 

Parallels  H-Sphere  Winbox  2.5  and  up  does  not  support  Serv-U.  Migrate  Serv-U  to  MS- 
FTP  before  updating  Winbox  to  Parallels  H-Sphere  2.5  and  up  from  older  version.  To 
do  this,  perform  the  steps  listed  below. 


In  this  section: 

Step  1.  Create  a User  Account  and  User  FTP  Accounts  in  IIS  FTP 275 

Step  2.  Reset  NTFS  Permissions 277 

Step  3.  Recover  Winbox  quota 278 

Step  4.  Reset  Anonymous  Access  for  All  User  Domains  in  IIS 278 
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Step  1 . Create  a User  Account  and  User  FTP  Accounts 
in  IIS  FTP 

Before  creating  a user  account  and  user  FTP  accounts,  make  sure  IIS  FTP  is  installed. 
Then  perform  the  following: 

1 Export  all  usernames  and  passwords  for  physical  server  from  CP 
database  to  a file.  For  this: 

1.  Login  to  CP  under  root: 

su  -1  cpanel 

psql  hsphere  wwwuser 

2.  Run: 

select  login,  password  from  unix_user  where  hostid=??? 

Replace  ???  with  ID  of  the  necessary  Logical  Server 

2 Write  down  the  result  in  the  users  . txt  file  in  a folder 

/c/fiVe:J\hsphere\scripts\  (e.g.  c:\hsphere\scripts\).  The 

format  of  results  is  as  follows: 

username  pwd 
username  pwd 

3 Make  the  following  alterations  to  the  hsphere\scripts\conf . inc 
file: 

1.  Change  ftpServer  = "SERV-U"  to  ftpServer  = "IIS" 

2.  Run  regedit 

3.  GO  tO  HKEY_LOCAL_MACHINE\SOFTWARE\ Psoft\HSphere\ Settings  and 
Set  IIS  FtpType 

4.  Go  to 

HKEY_LOCAL_MACHINE\SOFTWARE\ Psof t\HSphere\HsServULayer \Acce 
ss\,  and  delete  the  Users  key.  Then  recreate  the  empty  Users  key. 

5.  Restart  hs svc  service  in  cmd  window: 

net  stop  hssvc 
net  start  hssvc 

6.  restart  hsphere  service  in  cmd  window: 

net  stop  hsphere 
net  start  hsphere 

4 Create  IIS  Metabase  backup. 

5 Stop  IIS: 

1.  Go  to  cmd 

2.  Run: 

iisreset/ stop 
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6 Rename  Hshome  folder  to  1 Hshome  (e.g.  d:  \lhshome)  and  create 
empty  Hshome  folder  (e.g.  d:  \Hshome).  If  it  is  possible,  create  the 
backup  of  hshome  folder. 

7 Create  createusersp  . asp  script  in  the  Hsphere\scripts\ 

folder: 

<%@  LANGUAGE= JScript  %>  <!--  tinclude  file  =" consts . inc"  --> 
<!--  #include  file  ="conf.inc"  -->  <%  Server . ScriptTimeout  = 
600  inetSrv  = Server . CreateObject (comRsrcManager) 

Server . Execute (" /cfg/set-config . asp" ) fs  = new 
ActiveXObj ect ( "Scripting . FileSystemObj ect" ) ; a = 
fs . OpenTextFile (Server . MapPath (" /cfg/users . txt" ) , 1,  false); 
diskQuota  = Server . CreateObj ect ( "Microsoft . DiskQuota . 1 " ) while 
( ! a . AtEndOfLine)  { record  = a . ReadLine ( ) ; tokens  = 
record. split (new  RegExp("[  \n\r\t]"));  user  = tokens [0]; 
password  = tokens [1];  errCode  = 0 aOptions  = new 
Array (useDedicatedUsersGroup)  flags  = new  Array (1,  2,  4,  8, 

16,  32,  64,  128,  256,  512,  1024,  2048,  4096,  8192,  16384) 
options  = 0 for  (i  =0;  i < aOptions . length;  i ++)  { if 

(aOptions [i]  !=  0)  options  |=  flags [i]  } errCode  = 

inetSrv . CreateUser (user , usersHome  + "\\"  + user,  "settler", 
password,  logPath,  options)  if  (errCode  !=  0) 

Response . Write ( "User : " + user  + " f ailed<BR>\n" ) else 
Response . Write ( "User : " + user  + " = Ok<BR>\n") 

Response . Flush ( ) } a.Close () ; %> 

8 Run  in  browser  window  http://Tarqet  IP/cfq/createusersp.asp  Then 
put  an  hsadmin  login  and  password  in  authentication  window 

9 Delete  empty  Hshome  folder,  and  rename  1 Hshome  to  Hshome.  Start 
IIS 

10  Check  if  FTP  accounts  have  been  created  for  all  users 
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Step  2.  Reset  NTFS  Permissions 

1 Download  Recreation  scripts  from 
http://downioad.hsphere.parallels.com/shiv/WinBox/ReCreateAddScrip 

ts.zip  in  a zip  archive  and  unpack  them  to  a separate  directory  on  the 
Winbox,  for  example  recreation_scripts. 

2 Set  NTFS  permission  for  Hshome  folder: 

3 Download  the  setscrt.exe  utility  from 
http://download.hsphere.parallels.com/shiv/WinBox/SetScrt.exe 

a Run  it  to  set  correct  owner  and  NTFS  permissions  on  user  home  directories:  s 
etscrt  [-owner]  [-ntfs]  > setscrt.log 

b Running  the  setscrt  utility  with  the  -owner  and  -ntfs  options  separately,  will  break 
the  process  in  two: 

setscrt  -owner  > setscrt_owner.log 
setscrt  -ntfs  > setscrt_ntfs.log 

c Check  the  log  files  for  report. 

4 (skip  this  step,  if  your  Parallels  H-Sphere  version  is  2.5+) 

Reinstall  ASP.NET  for  all  accounts  that  have  it  enabled  in  CP 

a Get  users  and  domains  with  installed  ASP.NET  from  CP  database.  On  this  step, 
the  scripts  will  be  used  in  the  recreation_scripts  directory. 

b Log  into  the  system  database  and  run  the  following  DB  query  to  select  the 
domain  names  with  ASP.NET  support  enabled: 

select  d. name , i . hostnum  from  parent  child  pi, parent  child 
p2, parent  child  p3, parent  child  p4, domains  d, iis  vhost  i where 
i.host  id=???  and  pi . child  id  = i.id  and  pi. parent  id  = 
p2 . child  id  and  d.id  = p2. child  id  and 

p3. parent  id=p2. child  id  and  p4. parent  id=p3. child  id  and 
p4 . child_type=63 ; 

Replace  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

c Copy  the  results  of  the  query  into  a text  file  in  the  recreation_scripts  directory 
and  name  it,  for  instance,  aspnet.txt. 

d Enter  the  recreation_scripts  directory  and  run  the  following  command: 
aspnetprepare.bat  %1  %2  %3  %4  > aspnet_links.txt 
where: 

- rem  %1  - file  name,  e.g.  aspnet.txt 

- rem  %2  - Winbox  IP 

- rem  %3  - Parallels  H-Sphere  login  used  at  Winbox  installation 

- rem  %4  - Parallels  H-Sphere  password  used  at  Winbox  installation 

e Open  aspnet_links.txt  and  remove  the  first  part  leaving  only  the  list  of  links, 
f Run  the  following  command: 

WGET . EXE  -i  aspnet_links . txt 

This  will  recreate  all  ASP.NET  resources  on  the  Winbox. 
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Step  3.  Recover  Winbox  quota 

1 Log  into  the  system  database  (on  page  65)  and  run  the  following  DB 
query  to  select  the  users  and  their  space  limit: 

select  unix  user. login,  quotas. size  mb  from  unix  user, 
parent  child,  quotas  where  hostid=???  and 
parent  child. parent  id=unix  user. id  and 
parent  child. child  id=quotas . id  and 
parent  child. child  type=4001; 

Replace  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

2 Copy  the  results  of  the  query  into  a text  file  in  the  recreation_scripts 
directory  and  name  it,  for  instance,  quotat.txt. 

3 Enter  the  recreation_scripts  directory  and  run  the  following  command: 

Rquota.bat  %1  %2  %3  %4  > quota.txt 

where: 

- rem  %1  - file  name,  e.g.  quota.txt 

- rem  %2  - Winbox  IP 

- rem  %3  - Parallels  H-Sphere  login  used  at  Winbox  installation 

- rem  %4  - Parallels  H-Sphere  password  used  at  Winbox  installation 

4 Open  quota.txt  and  remove  the  first  part  leaving  only  the  list  of  links. 

5 Recreate  quota  resource  on  the  Winbox: 

WGET.EXE  -i  quota.txt 


Step  4.  Reset  Anonymous  Access  for  All  User  Domains 
in  IIS 

1 Create  setun . j s file  with  the  help  of  Notepad  with  the  following 
content: 

oldHome  = new  String (WScript . Arguments . item ( 0 ))  ; 
oldHome  = oldHome . toLowerCase ()  ; 
web  = GetObject ("IIS : //LocalHost/W3SVC" ) ; 
allWeb  = new  Enumerator (web) ; 

var  newDocRootPath,  oldDocRootPath,  stage  = 0; 
for  ( ; ! allWeb . atEnd ( ) ; allWeb .moveNext ( ) ) 

{ 

if  (isNaN  (parselnt (allWeb . item (). name) ) ) continue; 
docRoot  = GetOb j ect ( " IIS : //LocalHost/W3SVC/ " + 
allWeb . item ( ) .name  + "/ROOT"); 
docRoot . KeyType  = " IIsWebVirtualDir" ; 
docRoot . Setlnf o ( ) ; 

oldDocRootPath  = new  String (docRoot . Path) ; 
oldDocRootPath  = oldDocRootPath . toLowerCase ()  ; 

WScript . Echo ( "Site : " + allWeb . item (). name) ; 
if  (oldDocRootPath . indexOf (oldHome . toLowerCase () ) ==  -1) 

{ WScript . Echo ( "Site  " + allWeb . item ( ) .name  + " is  not 
Parallels  H-Sphere  web  site"); 
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continue; 

} 

tokens  = docRoot . Get ( "Path" ). split (new  RegExp ("\\\\") ) ; 
username  = tokens [tokens . length-2 ] ; 
docRoot . Put (" AnonymousUserName" , username) ; 

docRoot . Put ( "AnonymousPasswordSync" , 1 ) ; 
docRoot . Setlnfo ( ) ; 

WScript . Echo ( "Document  root  for  " + allWeb . item ( ) .name  + " web 
site  has  been  changed  to  " + newDocRootPath) ; 

} 

2 Run  in  cmd  window: 

cscript  setun.js  [path  to  Hshome] 

Example: 

cscript  setun.js  e:\hshome 


Note:  anonymous  access  is  reset  only  if  domain  properties  path  contains  hshome 
folder  and  if  domain  is  created  by  Parallels  H-Sphere. 

3 Restart  IIS  (on  page  242).  Go  to  cmd->iisreset 

4 Go  to  hsphere.net\bin\.  Open  install. history  file  with  the 
help  of  Notepad,  select  all  the  text,  and  delete  it,  save  empty 

install,  history  file. 

5 Run  Parallels  H-Sphere  updater  for  Winbox. 

6 If  FTP  subaccounts  were  created  in  Serv-U,  recreate  them  via  CP 
interface  manually. 

7 Open  SOAP  port  10125  for  data  communication  between  Control 
Panel  and  Windows  server,  in  the  hsphere . properties  file  on  the 
Control  Panel  box. 


280  Windows  Servers 


Preparing  Servers  for  MS  Exchange 
Hosting  (Hosted  Messaging  and 
Collaboration  3.0) 


Note:  This  is  the  instruction  for  Hosted  Messaging  and  Collaboration  3.0. 


Before  you  start  using  MS  Exchange  hosting,  you  need  to  prepare  at  least  2 servers, 
separately  of  Parallels  H-Sphere,  with  the  following  software  installed: 

1 Server  1 (Primary  Domain  Controller):  Windows  2003  SP1 , Active  Directory 
Domain  Controller 

2 Server  2 (MS  Exchange  Server):  Windows  2003  SP1 , MSSQL  2000  SP3,  MS 
Exchange  2003  SP1,  Hosted  Messaging  and  Collaboration  3.0,  WS  Exchange 
Provider  Adapter  Namespace 

> To  prepare  Servers  for  MS  Exchange  Hosting: 

1 Install  Required  Software  on  the  Servers  (on  page  281) 

2 Deploy  Hosted  Messaging  and  Collaboration  (on  page  282) 

3 Install  WS  Exchange  Provider  Adapter  Namespace  (on  page  294) 

4 Create  Reseller  Organization  Unit  (on  page  294) 


In  this  section: 


Step  1.  Install  Required  Software  on  the  Servers 281 

Step  2.  Deploy  Hosted  Messaging  and  Collaboration 282 

Step  3.  Install  WS  Exchange  Provider  Adapter  Namespace 294 

Step  4.  Create  Reseller  Organization  Unit 294 
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Step  1 . Install  Required  Software  on  the  Servers 

> To  install  required  software  on  the  servers 

1 Install  Window  2003  SP1  on  both  servers  with  English  language 
interface. 

2 Install  MDAC  2.8  on  Server  2. 

3 Install  IIS  and  ASP.NET  on  Server  2: 

1 . On  the  taskbar,  click  Start,  click  Control  Panel,  select  Add  or  Remove  Programs, 
and  then  click  Add/Remove  Windows  Components. 

2.  Select  Application  Server,  and  then  click  Details. 

3.  Select  Internet  Information  Services  (IIS),  and  then  click  Details. 

4.  Install  the  following  components:  Internet  Information  Services  Manager,  World 
Wide  Web  Services,  Common  Files,  ASP.NET 

5.  Click  OK,  click  OK  again,  and  then  click  Next. 

6.  After  the  wizard  completes,  click  Finish  and  close  the  Add  or  Remove  Programs 
dialog  box. 

4 Install  MSSQL  Server  2000  on  Server  2. 

5 Install  MSSQL  Server  2000  SP3  on  Server  2. 

6 Enable  Network  DTC  and  COM+  Network  Access 

1 . On  the  taskbar,  click  Start,  open  Control  Panel,  and  then  click  Add  or  Remove 
Programs. 

2.  Click  the  Add/Remove  Windows  Components  button. 

3.  Highlight  Application  Server,  and  then  click  Details. 

4.  Select  EnableNetwork  COM+  access. 

5.  Select  EnableNetwork  DTC  access.  Click  OK. 

6.  Click  Next.  When  the  Windows  Components  Wizard  completes,  click  Finish. 

7 Enable  Inbound  and  Outbound  DTC  Access  on  Server  2 

1 . Click  Start,  point  to  All  Programs,  point  to  Administrative  Tools,  and  then  click 
Component  Services. 

2.  Click  and  expand  Component  Services,  and  then  click  and  expand  Computers. 

3.  Right-click  My  Computer,  and  then  select  Properties. 

4.  Select  the  MSDTC  Tab. 

5.  Click  the  Security  Configuration  button. 

6.  Ensure  that  Network  DTC  Access  is  enabled.  Then,  ensure  that  the  Allow 
Inbound  and  Allow  Outbound  options  are  selected  in  the  Transaction  Manager 
Communication  section.  Leave  all  other  options  as  default. 

7.  Click  OK  to  save  the  settings.  Select  Yes  if  you  are  prompted  to  restart  the 
service. 

8 Obtain  Flosted  Messaging  and  Collaboration  3.0  media. 
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9 Install  Active  Directory  Domain  Controller  on  Server  1 using  the 
dcpromo.exe  tool  in  Windows  root  directory. 

10  Join  Server  2 to  installed  domain. 

11  Log  on  to  Server  2 as  a member  of  the  Domain  Administrators  group. 

12  Install  MS  Exchange  server  2003  on  Server  2. 

13  Install  MS  Exchange  server  2003  SP1  on  Server  2. 

Step  2.  Deploy  Hosted  Messaging  and  Collaboration 

> To  deploy  Hosted  Messaging  and  Collaboration 

1 Log  on  to  Server  2 as  a member  of  the  Domain  Administrators  group. 

2 Install  the  MPS  (Microsoft  Provisioning  Service)  deployment  tool. 

1 . Quit  all  running  programs. 

2.  Open  command  prompt,  and  change  the  directory  to 

SolutionMedia\Service  Provisioning\Deployment  Tool. 

3.  To  install  the  Deployment  Tool  on  Server  2,  run  the  following  from  the  command 
prompt:  cscript  initdeploymenttool . wsf . 

Note:  If  you  are  not  installing  from  CD,  you  will  be  prompted  to  enter  a path  to  the 
root  directory  of  the  solution  media  source  files. 

4.  When  prompted  for  the  server  name  for  configuration  files,  enter  Error! 
Hyperlink  reference  not  valid.  2 name>,  and  then  click  OK. 

5.  When  prompted  for  the  server  name  for  installation  files,  enter  Error!  Hyperlink 
reference  not  valid.  2 name>,  and  then  click  OK. 

6.  In  the  confirm  configuration  dialog  box,  click  Yes  if  the  settings  are  correct,  or 
click  No  to  cancel. 

7.  In  Do  you  want  to  install  the  deployment  tool  to  the  local  computer?  dialog  box, 
click  Yes.  A shortcut  for  the  Deployment  Tool  will  be  added  to  the  desktop  of 
Server  2. 

3 Install  the  MPF  (Microsoft  Provisioning  Framework)  Engine  and 
Database 

1 . Run  the  MPS  Deployment  Tool,  and  then  click  the  Servers  tab. 

2.  Under  SQL  Servers,  click  Add. 

3.  Enter  <Server  2 name>,and  then  click  OK. 

4.  Under  MPS  Servers,  click  Add. 

5.  Enter  the  name  of  the  MPF  Engine  server  as  <Server  2 name>,  and  then  click 
OK. 

6.  In  the  Requirements  Status  pane,  expand  the  Active  Directory  component,  right- 
click  Native  Mode,  and  then  select  User  input  on  the  contextual  menu  that 
appears.  In  the  Active  Directory  Native  Mode  dialog  box,  click  OK. 
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7.  Under  the  Active  Directory  component,  right-click  List  Object  Mode,  and  then 
select  User  Input  on  the  contextual  menu  that  appears.  The  Active  Directory/list 
Object  Mode  dialog  box  appears  and  prompts  you  as  to  whether  or  not  you  want 
to  proceed.  Click  OK. 

8.  In  the  Requirements  Status  pane,  right-click  the  MPF  Engine  component,  select 
Install  on  Server,  and  then  click  <Server  2 name>. 

9.  The  icon  next  to  the  MPF  Engine  component  changes  to  a silver  disk  to  indicate 
that  you  have  scheduled  the  installation  of  this  component. 

Note:  Because  of  inherent  dependencies,  when  you  configure  the  MPF  Engine  to 
be  installed  on  Server  2,  other  core  MPS  components  are  also  installed  on  Server 
2,  and  the  MPFServiceAcct  is  scheduled  to  be  created  in  Active  Directory. 

10.  In  the  Requirements  Status  pane,  right-click  the  MPF  Config  Database 
component,  select  Install  on  SQL  Server,  and  then  click  <Server  2 name>. 

1 1 . Repeat  step  3.1 0 for  each  of  the  MPF  database  components: 

■ Resource  Manager  Database 

■ MPF  Audit  Database 

■ MPF  Transaction  Database 

12.  In  the  Requirements  Status  pane,  right-click  the  Windows-based  Hosting 
component,  and  then  select  Install  this  Group  to  install  all  the  components.  The 
Install  This  Group  dialog  box  will  display  the  list  of  items  to  be  installed  and 
actions  to  be  performed.  Click  OK. 

13.  Click  Start  Deployment  to  start  the  installation  of  the  MPF  Engine,  databases, 
and  namespaces/providers  on  the  server. 

14.  Monitor  the  deployment  session  on  the  Install  Details  tab. 

1 5.  When  the  deployment  is  complete,  on  the  Action  History  tab,  click  View  Details 
to  review  events. 

16.  Close  the  Provisioning  Deployment  Tool. 

Note:  When  deployment  completes,  you  will  see  that  the  following  Namespace 
Initialization  procedures  are  displayed  with  a red  X,  and  the  Install  Details  pane 
displays  an  unable  to  create  the  credential  error. 

Managed  Flelpers:lnitializeNamespaceSecurity 
Managed  Web  Flosting:lnitializeNamespaceSecurity 
Managed  Sharepoint  Flosting:lnitializeNamespaceSecurity 
This  is  an  expected  error. 

4 Verify  the  MPFClientAccts  Group  on  Server  2 

1 . Click  Start,  point  to  AllPrograms,  point  to  AdministrativeTools,  and  then  click 
Computer  Management. 

2.  Expand  Local  Users  and  Groups,  and  then  click  Groups. 

3.  Double-click  Distributed  COM  Users,  and  then  click  the  Members  tab. 

4.  Verify  that  the  <domain  name>\MPFCIientAccts  group  is  member  of  Distributed 
COM  Users  group.  Click  OK. 

5.  Click  OK  to  close  the  Distributed  COM  Users  Properties  dialog  box. 
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5 Add  MPFServiceAccts  to  the  Local  Administrators  Group 

1 . On  the  taskbar,  click  Start,  click  All  Programs,  click  Administrative  Tools,  and 
then  click  Computer  Management. 

2.  Expand  Local  Users  and  Groups,  and  then  click  Groups. 

3.  Double-click  the  Administrators  group. 

4.  Click  Add,  and  then  enter  MPFServiceAccts.  Select  the  Check  Names  check 
box  to  make  sure  that  the  name  resolves,  and  then  click  OK. 

5.  Click  OK  to  close  the  Administrator  Properties  window. 

6 Reboot  Server  2 

7 Initialize  Namespaces 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  expand  the  Namespace  Initialization 
component.  Right-click  Managed  Helpers:lnitializeADforHosting,  and  then  select 
User  Input. 

3.  When  prompted  for  the  name  of  the  hosting  organization,  accept  the  default  of 
Hosting,  and  then  click  OK. 

4.  Right-click  Managed  Helpers:lnitializeADforHosting,  and  then  select  Execute 
Initialization  Procedure. 

5.  In  the  Confirm  Operation  dialog  box,  click  Yes. 

6.  Right-click  Managed  Helpers:lnitializeNamespaceSecurity,  and  then  select 
Execute  Initialization  Procedure. 

7.  In  the  Confirm  Operation  dialog  box,  click 

8.  When  the  deployment  completes,  close  the  MPS  Deployment  Tool. 

8 Install  the  Plans  Database 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  right-click  Plans  Database,  select  Install  on 
Server,  and  then  select  <Server  2 name>. 

3.  Click  Start  Deployment. 

4.  When  deployment  completes,  close  the  MPS  Deployment  Tool. 

5.  Run  the  MPS  Deployment  Tool. 

6.  In  the  Requirements  Status  pane,  expand  Namespace  Initialization. 

7.  Right-click  Managed  Helpers:  InitializePlanDatabase,  and  then  select  Execute 
Initialization  Procedure. 

8.  In  the  Confirm  Operation  dialog  box,  click  Yes. 

9.  When  deployment  completes,  close  the  MPS  Deployment  Tool. 

9 Install  the  MPS  Web  Services  on  Server  2 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  right-click  Web  Service,  select  Install  on 
Server,  and  then  select  <Server  2 name>. 

3.  Below  Web  Service,  right-click  <Server  2 name>,  and  then  select  User  Input. 
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4.  In  the  New  Virtual  Directory  box,  enter  MPSWS,  and  then  click  OK. 

Note:  After  you  assign  the  Web  service  and  input  the  virtual  directory  name,  the 

MPF  Client  will  automatically  be  assigned  for  installation  on  Server  2 

5.  Click  Start  Deployment. 

6.  When  the  deployment  completes,  click  OK,  and  then  quit  the  MPS  Deployment 
Tool. 

10  Install  Resource  Manager  Web  Client  on  Server  2 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  right-click  Resource  Manager  Web  Client, 
select  Install  on  Server,  and  then  select  <Server  2 name>. 

3.  Below  Web  Service,  right-click  <Server  2 name>,  and  then  select  User  Input. 

4.  In  the  New  Virtual  Directory  box,  enter  ResourceManagerWebClient,  and  then 
click  OK. 

5.  Click  Start  Deployment. 

6.  When  the  deployment  completes,  click  OK,  and  then  quit  the  MPS  Deployment 
Tool. 

11  Initialize  Hosted  Exchange  Provisioning  Namespaces 

1.  Run  the  MPS  Deployment  Tool. 

2.  Expand  Namespace  Initialization. 

3.  Right-click  Hosted  Exchange:  InitializeHostedExchange,  and  then  select 
Execute  Initialization  Procedure.  At  the  Confirm  Operation  dialog  box,  click  Yes. 

12  Configure  the  MPFServiceAccts  Group  As  Exchange  Full 

Administrator 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  right-click  the  top  node  where  the  name  of  your  Exchange 
organization  is  displayed,  and  then  click  Delegate  control  to  start  the  wizard. 

3.  Click  Next,  click  Add,  click  Browse,  select  MPFServiceAccts  from  the  list,  and 
then  click  OK. 

4.  On  the  drop-down  menu,  click  Exchange  Full  Administrator,  click  OK,  click  Next, 
and  then  click  Finish.  If  prompted  with  a security  dialog  box,  click  OK. 

13  Configure  the  Microsoft  Provisioning  System  Server  for  Hosted 

Exchange 

1 . Run  the  MPS  Provisioning  Deployment  Tool. 

2.  Under  Microsoft  Exchange,  right-click  Delegate  Exchange  Administration,  then 
select  Force  State.  At  the  Force  State  dialog  box,  select  the  Verified  radio  button 
and  click  OK. 

3.  Under  Microsoft  Exchange,  right-click  Disable  Domain  RUS,  then  select  Install. 
The  Confirm  Operation  dialog  box  appears  and  prompts  you  as  to  whether  or 
not  you  want  to  proceed  with  an  action  that  has  an  immediate  effect.  Click  Yes. 
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4.  Under  Microsoft  Exchange,  right-click  Secure  All  Address  Lists,  then  select 
Install.  The  Confirm  Operation  dialog  box  appears  and  prompts  you  as  to 
whether  or  not  you  want  to  proceed  with  an  action  that  has  an  immediate  effect. 
Click  Yes. 

5.  Under  Microsoft  Exchange,  right-click  Native  Mode,  then  select  Install.  The 
Confirm  Operation  dialog  box  appears  and  prompts  you  as  to  whether  or  not  you 
want  to  proceed  with  an  action  that  has  an  immediate  effect.  Click  Yes. 

Check  the  log  information  at  the  bottom  of  the  Configuration  Wizard  screen  to 
verify  that  the  configuration  was  successfully  set. 

14  Configure  the  MPSExchangeAccts  Group  As  Exchange  Full 

Administrator 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  right-click  the  top  node  where  the  name  of  your  Exchange 
organization  is  displayed,  and  then  click  Delegate  control  to  start  the  wizard. 

3.  Click  Next,  click  Add,  click  Browse,  select  MPSExchangeAccts  from  the  list,  and 
then  click  OK. 

4.  On  the  drop-down  menu,  click  Exchange  Full  Administrator,  click  OK,  click  Next, 
and  then  click  Finish.  If  prompted  with  a security  dialog  box,  click  OK. 

15  Configure  the  All  Address  Lists  Container 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  click  the  Recipients  node,  expand  the  tree. 

3.  Right-click  the  All  Address  Lists  and  select  Properties. 

4.  Click  the  Security  tab,  click  Advanced,  and  then  click  Add  under  Permissions. 

5.  In  the  Name  text  box,  type  MPSExchangeAccts,  and  then  click  OK. 

6.  In  the  Apply  onto  list,  select  This  object  and  subcontainers. 

7.  In  the  Permissions  list,  click  Full  Control. 

8.  Click  OK  three  times. 

16  Add  the  MPSExchangeAccts  Group  to  Local  Administrators  Group 

17  Create  Mailbox  Stores  for  Flosted  Exchange 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  expand  Servers,  then  expand  <Exchange  Server>,  and  then 
expand  First  Storage  Group. 

3.  Create  any  appropriate  mailbox  stores  will  be  used  as  a Business  Mailstores. 

18  Initialize  Resource  Management 

1 . Launch  Internet  Explorer,  and  go  to 
http://localhost/ResourceManagerWebClient/QueryResources.aspx. 

2.  When  prompted  for  Username  and  Password,  log  in  as  <domain 
name>\Administrator. 
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3.  Enter  <Server  1 fullname>  in  the  Preferred  Domain  Controller  text  box.  Click 
Submit. 

4.  In  the  left  pane,  click  Exchange  Resource  Manager.  Then,  select  the  Business 
Mailstores  tab. 

5.  Add  Business  Mailstore  resources. 


Important:  The  <shared>  value  should  always  be  set  to  1 for  Business  mail  stores 

6.  In  the  left  pane,  click  Exchange  Resource  Manager.  Then,  select  the  Public 
Stores  tab. 

7.  Under  Publicstores,  click  Add  New  Resource. 

8.  Add  Public  Store  resources 

9.  In  the  left  pane,  click  Exchange  Resource  Manager,  and  then,  select  the  OAB 
Servers  tab. 

10.  Under  OAB  Servers,  click  Add  New  Resource. 

1 1 . Add  OAB  Server  resources. 

19  Install  the  Hosted  Exchange  Offline  Address  Book  (OAB)  and  Update 

Batch  Application  (on  page  289) 

20  Deploy  the  MPS  Sample  Web  Client 

1 . Run  SetupMPSSampleWeb.msi  from  the  Windows-based  Hosting  distribution 
media  in  the  \Samples\Provisioning\MPSSampleWeb  directory. 

2.  On  the  MPPSSampleWeb  Setup  Wizard  Welcome  page,  click  Next. 

3.  On  the  Select  Installation  Address  page,  accept  the  default  Virtual  Directory 
(MPSSampleWeb)  and  Port  (80),  and  then  click  Next. 

4.  On  the  Confirm  Installation  page,  click  Next. 

5.  On  the  Installation  Complete  page,  click  Close. 

6.  Open  the  Internet  Information  Services  (IIS)  Manager,  and  then  expand  the 
default  Web  site. 

7.  Right-click  MPSSampleWeb,  and  then  select  Properties. 

8.  Click  the  Directory  Security  tab,  and  then,  under  Authentication  and  access 
control,  click  Edit. 

9.  Clear  the  Enable  atupMPSSampleWeb.msi  from  the  Windows-based  Hosting 
distribution  media  in  the  \Samples\Provisioning\MPSSampleWeb  directory. 

10.  Ensure  that  the  Integrated  Windows  Authentication  check  box  is  cleared. 

1 1 . Select  the  Basic  authentication  check  box,  and  then,  in  the  warning  dialog  box, 
click  Yes. 

1 2.  Enter  a backslash  “\”  in  the  default  domain  field. 

1 3.  Click  OK,  and  then  click  OK  again. 

14.  Close  the  IIS  Manager  window. 

15.  Edit  the  Web.Config  file  in  the  root  directory  of  the  MPS  Sample  Web  Client 
(usually  \inetpub\wwwroot\MPSSampleWeb).  Set  the  following  preferredDC  and 
DefaultNamingContext  key  values  to  your  preferred  domain  controller  and 
default  naming  context.  For  example: 


288  Windows  Servers 


<appSettings> 

<add  key="pref erredDC"  value="Server  1 full  name>"/> 

<add  key="Def aultNamingContext" 

Value="DC=domain  name  parti , DC=domain  name  part2"/> 

21  Disable  the  EventSink: 

1 . Go  to  C:\Program  FilesWIicrosoft  Hosting\Provisioning\MPSWS\  and  open  file 
web.config. 

2.  Find  the  odd  key="EnableEventSink"  value="1  "/>  string  and  change  value  to  0 
(odd  key="EnableEventSink"  value="0"/>) 

3.  Save  changes. 

It  will  allow  creating  Exchange  Recipient  Policy  for  new  SMTP  domains. 

In  this  section: 

Installing  the  Plosted  Exchange  Offline  Address  Book  (OAB)  Update  Batch  Application  289 
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Installing  the  Hosted  Exchange  Offline  Address  Book  (OAB) 
Update  Batch  Application 

The  Hosted  Exchange  OAB  Update  batch  application  runs  on  a daily  schedule  in  order 

to  rebuild  OAB  for  organizations  that  have  had  membership  modifications. 

> To  install  and  configure  it  to  run  as  a scheduled  job,  do  the  following: 

1 Install  the  Hosted  Exchange  OAB  Update  Batch  Application  (on  page 
290) 

2 Configure  Security  for  the  Hosted  Exchange  OAB  Update  Batch 
Application  Registry  Keys  (on  page  291) 

3 Configure  Security  Access  for  the  Applications'  Local  File  Resources 
(on  page  292) 

4 Configure  Option  Settings  for  the  Hosted  Exchange  OAB  Update 
Batch  Application  (on  page  292) 

5 Execute  the  Hosted  Exchange  OAB  Update  Batch  Application  (on 
page  293) 

6 Create  a Scheduled  Task  for  the  Hosted  Exchange  OAB  Update  Batch 
Application  (on  page  293) 


In  this  section: 

Step  1.  Install  the  Hosted  Exchange  OAB  Update  Batch  Application 290 

Step  2.  Configure  Security  for  the  Hosted  Exchange  OAB  Update  Batch  Application  Registry  Keys 

Step  3.  Configure  Security  Access  For  the  Applications  Local  File  Resources  ..292 

Step  4.  Configure  Option  Settings  for  the  Hosted  Exchange  OAB  Update  Batch  Application  292 

Step  5.  Execute  the  Hosted  Exchange  OAB  Update  Batch  Application 293 

Step  6.  Create  a Scheduled  Task  for  the  Hosted  Exchange  OAB  Update  Batch  Application  293 
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Step  1.  Install  the  Hosted  Exchange  OAB  Update  Batch  Application 

1 Log  on  to  Server2(Exchange)  using  an  account  that  is  a member  of 
the  Domain  Administrators  group. 

2 From  a command  prompt  in  the  Service 
Provisioning\MPS\Install  folder,  run  the 
ExchangeOABUpdate  . msi  file.  You  must  specify  a password  as 
follows: 

msiexec.exe  /i  ExchangeOABUpdate .msi  OABUSERPW=password 
where  password  meets  your  Active  Directory  security  requirements. 

3 On  the  License  Agreement  page,  select  I accept  the  terms  in  the 
license  agreement,  and  then  click  Next. 

4 On  the  Customer  Information  page,  enter  the  User  Name  and 
Organization,  and  then  click  Next. 

5 On  the  Setup  Type  page,  select  Complete,  and  then  click  Next. 

6 Click  Install. 

7 Click  Finish  to  complete  the  installation  and  close  the  Installation 
Wizard. 

8 Log  on  to  Serverl  (DC)  using  an  account  that  is  a member  of  the 
Domain  Administrators  group. 

9 On  the  taskbar,  click  Start,  point  to  Administrative  Tools,  and  then 
click  Active  Directory  Users  and  Computers. 

10  Expand  fabrikam.com,  and  then  select  Users. 

11  In  the  right  pane,  locate  and  right-click  the  MPFClientAccts  user 
object,  and  then  select  Properties. 

12  In  the  Properties  dialog  box,  select  the  Members  tab. 

13  Click  Add,  type  MPSOABUpdateAccts  and  then  click  Check  Names. 
Verify  that  MPSOABUpdateAccts  is  underlined,  and  then  click  OK. 

14  Click  OK  to  close  the  Properties  dialog  box. 

Note:  By  default,  the  MPSOabUpdateAcct  is  the  only  account  that  can  execute  the 

HEOabUpdate . exe  application.  If  you  want  other  users  to  be  able  to  run  the 

application,  you  must  add  them  to  the  MpsOabUpdateAccts  group.  After  adding 

users  to  the  MpsOabUpdateAccts  group,  you  muse  restart  the  Microsoft  Provisioning 

Framework  (MPF)  engine  for  the  changes  to  take  effect. 
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Step  2.  Configure  Security  for  the  Hosted  Exchange  OAB  Update  Batch 
Application  Registry  Keys 

In  the  following  procedures  you  will  configure  security  access  for  the  applications 
registry  keys,  local  resources,  and  MPF  procedures. 


WARNING:  Incorrectly  editing  the  registry  can  cause  serious  problems  that  may  require 
you  to  reinstall  your  operating  system.  Problems  resulting  from  editing  the  registry 
incorrectly  may  not  be  resolved.  Before  editing  the  registry,  back  up  any  valuable  data. 


> To  configure  security  access  for  the  Hosted  Exchange  OAB  Update  Batch  Application 
registry  keys: 

1 Log  onto  Server2(Exchange)  using  an  account  that  is  a member  of  the 
Domain  Administrators  group 

2 Start  Registry  Editor  (regedit). 

3 Navigate  to  the 

HKEY_LOCAL_MACHINE \ Software \Microsof t\ Provisio ning\ He 
OabUpdate  key. 

4 Click  the  Edit  menu  and  select  Permissions. 

5 In  the  Permissions  for  HeOabUpdate  dialog  box,  click  Add. 

6 Type  MpsOabUpdateAccts  and  click  Check  Names  to  verify  that  the 
group  exists. 

7 Click  OK. 

8 Click  Advanced. 

9 Select  MPSOabUpdateAccts  in  the  permissions  entries  list  and  click 
Edit. 

10  In  the  Apply  onto  list,  ensure  that  this  key  and  subkeys  is  selected. 

11  In  the  Permissions  list,  leave  the  default  values  selected,  and  then 
select  the  Allow  check  box  for  the  Set  Value  and  Create  Subkey 
permissions. 

12  Click  OK  three  times. 

13  Close  Registry  Editor. 
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Step  3.  Configure  Security  Access  For  the  Applications  Local  File  Resources 

> To  configure  security  access  for  the  Hosted  Exchange  OAB  Update  Batch  Application 
local  resources 

1 Open  File  Explorer  and  navigate  to  <drive>:  \ Program 
Files \Microsoft  Hos ting\Provis ioning. 

2 Right-click  the  Exchange  OAB  Update  directory  and  select  Properties. 

3 Select  the  Security  tab  and  click  Add. 

4 Type  MpsOabUpdateAccts  and  click  Check  Names  to  verify  that  the 
group  exists.  Click  OK. 

5 Ensure  that  the  Allow  check  box  for  the  Modify  permission  is  selected. 

6 Click  OK. 


Step  4.  Configure  Option  Settings  for  the  Hosted  Exchange  OAB  Update 
Batch  Application 

In  this  procedure,  you  will  edit  the  applications  configuration  file  to  change  settings  to 
appropriate  values  for  your  deployment. 

> To  configure  optional  settings  for  the  Hosted  Exchange  OAB  Update  Batch 
Application: 

1 Remove  the  read-only  attribute  from  :\Program  Files\Microsof t 
Hos t ing\ Provi sioning\Exchange  OAB 
Update\HeOabUpdate.exe.config,  and  then  open  the  file. 

2 Set  the  preferredDomainController  value  to  the  fully  qualified  domain 
name  (FQDN)  of  your  preferred  domain  controller  as  in  the  following 
example: 

<conf iguration> 

<appSettings> 

<add  key="eventLogLevel " value="Minimum"/> 

<add  key="screenLogLevel"  value="Minimum" /> 

<add  key="logAHEventsToFile"  value="true"/> 

<add  key= "preferredDomainController" 
value="AD01 . fabrikam. com"/> 

</appSettings> 

</configuration> 

Note:  AD01.fabrikam.com  is  full  computer  name  of  Serverl  (Domain  controller) 

3 Save  the  file  after  making  your  changes 
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Step  5.  Execute  the  Hosted  Exchange  OAB  Update  Batch  Application 

In  the  following  procedure  you  execute  the  Hosted  Exchange  OAB  Update  batch 
application  from  the  command  line. 

> To  execute  Hosted  Exchange  OAB  Update  from  a command  line: 

1 Open  a command  prompt  and  navigate  to  : \Program 
Files\Microsof t Hosting\Provisioning\  Exchange  OAB 
Update. 

2 Type  the  following,  and  press  Enter: 

HeOabUpdate . exe 

3 Close  the  command  prompt  when  the  application  has  finished 
processing. 


Step  6.  Create  a Scheduled  Task  for  the  Hosted  Exchange  OAB  Update 
Batch  Application 

In  the  following  procedures  you  will  create  a scheduled  task  for  the  application. 

> To  create  a scheduled  task  to  run  Hosted  Exchange  OAB  Update  daily 

1 Point  to  Settings,  and  then  click  Control  Panel. 

2 Double-click  Scheduled  Tasks. 

3 Double-click  Add  Scheduled  Task. 

4 In  the  Scheduled  Task  Wizard,  click  Next. 

5 Click  Browse,  and  then  select  AProgram  Files\Microsoft 
Hosting\Provisioning\Exchange  OAB  Update\HeOabUpdate.exe. 

6 Click  Open. 

7 Select  the  Daily  option,  and  then  click  Next. 

8 Set  Start  Time  to  6:00  AM. 

9 Click  Next. 

10  Enter  the  Fabrikam\MPSOabUpdateAcct  user  name  and  the  password 
for  this  account.  Click  Next. 

Where  Fabrikam  is  active  directory  domain  name 

Note:  Task  Scheduler  does  not  verify  that  the  password  you  enter  for  the 
MPSOabUpdateAcct  matches  the  password  set  for  the  user  in  Active  Directory.  If 
you  enter  an  incorrect  password,  the  task  will  fail  when  it  runs  at  its  scheduled  time. 


11  Click  Finish. 
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Step  3.  Install  WS  Exchange  Provider  Adapter 
Namespace 

WS  Exchange  Provider  Adapter  Namespace  (WS  stands  for  "Web  service")  provides 
communication  between  Parallels  H-Sphere  and  MS  Exchange  provider  via  HTTP  in 
order  to  manage  MS  Exchange  hosting  in  Parallels  H-  Sphere  CP. 

1 Download  WS  Exchange  Provider  Adapter  Namespace  installation: 
http://hsphere.parallels.com/download/wsexchanqeprovider.msi. 

2 Run  the  downloaded  MSI  file  and  follow  the  installation  instructions. 

Step  4.  Create  Reseller  Organization  Unit 

Create  reseller  organization  unit  under  which  Parallels  H-Sphere  users  signed  up  for 
MS  Exhange  plans  will  be  hosted.  On  Server  2: 

1 In  Internet  Explorer,  go  to  http://localhost/MPSSampleWeb 

2 When  prompted,  log  on  as  Domain  Administrator. 

3 Leave  the  Current  Reseller  and  Current  Customer  fields  empty. 

4 Select  the  General  tab. 

5 In  the  left-hand  pane,  click  Create  a Reseller  Organization. 

6 Enter  information  about  the  organization  in  the  appropriate  boxes  on 
the  Create  Reseller  Org  page 

7 Click  Submit  Request. 

8 When  the  request  completes,  you  can  review  the  XML  response  at  the 
bottom  of  the  page. 

After  that,  you  can  proceed  to  configuring  Microsoft  Provisioning  Framework  in  admin 
CP.  This  is  described  in  MS  Exchange  section  of  Parallels  H-Sphere  Service 
Administrator  Guide. 

That's  how  the  organization  unit  may  look  like  when  it  is  created  and  used  for  Parallels 
H-Sphere  hosting: 
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In  the  above  screenshot,  Organizationl  is  the  reseller  organization  unit,  and  its 
organization  units  like  exchange  are  Parallels  H-Sphere  user  accounts  with  emails  and 
distribution  lists. 


Preparing  Servers  for  MS  Exchange 
Hosting  (Hosted  Messaging  and 
Collaboration  3.5) 

Before  you  start  using  MS  Exchange  hosting,  you  need  to  prepare  at  least  2 servers, 
separately  of  Parallels  H-Sphere,  with  the  following  software  installed: 


1 Server  1 (Primary  Domain  Controller):  Windows  2003  SP1 , Active  Directory 
Domain  Controller 
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2 Server  2 (MS  Exchange  Server):  Windows  2003  SP1 , MSSQL  2000  SP3,  MS 
Exchange  2003  SP1,  Hosted  Messaging  and  Collaboration  3.5,  WS  Exchange 
Provider  Adapter  Namespace 

> To  prepare  Servers  for  MS  Exchange  Hosting: 

1 Install  Required  Software  on  the  Servers  (on  page  297) 

2 Deploy  Hosted  Messaging  and  Collaboration  (on  page  298) 

3 Install  WS  Exchange  Provider  Adapter  Namespace  (on  page  304) 

4 Create  Reseller  Organization  Unit  (on  page  304) 


In  this  section: 


Step  1.  Install  Required  Software  on  the  Servers 297 

Step  2.  Deploy  Hosted  Messaging  and  Collaboration 298 

Step  3.  Install  WS  Exchange  Provider  Adapter  Namespace 304 

Step  4.  Create  Reseller  Organization  Unit 304 


Windows  Servers 


297 


Step  1 . Install  Required  Software  on  the  Servers 

1 Install  Window  2003  SP1  on  both  servers  with  English  language 
interface. 

2 Install  MSXML4  from 

http://www.microsoft.com/downloads/details.aspx?FamilvlD=31 44b72b 

-b4f2-46da-b4b6-c5d7485f2b42&DisplayLanq=en  on  Server  2. 

3 Install  IIS  (WWW,  FTP,  SMTP,  NNNT)  and  ASP.NET  on  Server  2: 

1 . On  the  taskbar,  click  Start,  click  Control  Panel,  select  Add  or  Remove  Programs, 
and  then  click  Add/Remove  Windows  Components. 

2.  Select  Application  Server,  and  then  click  Details. 

3.  Select  Internet  Information  Services  (IIS),  and  then  click  Details. 

4.  Install  the  following  components:  Internet  Information  Services  Manager,  World 
Wide  Web  Services,  Common  Files,  ASP.NET 

5.  Click  OK,  click  OK  again,  and  then  click  Next. 

6.  After  the  wizard  completes,  click  Finish  and  close  the  Add  or  Remove  Programs 
dialog  box. 

4 Install  MSSQL  Server  2000  on  Server  2. 

5 Install  MSSQL  Server  2000  SP4  on  Server  2. 

6 Enable  Network  DTC  and  COM+  Network  Access 

1 . On  the  taskbar,  click  Start,  open  Control  Panel,  and  then  click  Add  or  Remove 
Programs. 

2.  Click  the  Add/Remove  Windows  Components  button. 

3.  Highlight  Application  Server,  and  then  click  Details. 

4.  Select  EnableNetwork  COM+  access. 

5.  Select  EnableNetwork  DTC  access.  Click  OK. 

6.  Click  Next.  When  the  Windows  Components  Wizard  completes,  click  Finish. 

7 Enable  Inbound  and  Outbound  DTC  Access  on  Server  2 

1 . Click  Start,  point  to  All  Programs,  point  to  Administrative  Tools,  and  then  click 
Component  Services. 

2.  Click  and  expand  Component  Services,  and  then  click  and  expand  Computers. 

3.  Right-click  My  Computer,  and  then  select  Properties. 

4.  Select  the  MSDTC  Tab. 

5.  Click  the  Security  Configuration  button. 

6.  Ensure  that  Network  DTC  Access  is  enabled.  Then,  ensure  that  the  Allow 
Inbound  and  Allow  Outbound  options  are  selected  in  the  Transaction  Manager 
Communication  section.  Leave  all  other  options  as  default. 

7.  Click  OK  to  save  the  settings.  Select  Yes  if  you  are  prompted  to  restart  the 
service. 

8 Obtain  Flosted  Messaging  and  Collaboration  3.5  media. 
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9 Install  Active  Directory  Domain  Controller  on  Server  1 using  the 
dcpromo.exe  tool  in  Windows  root  directory. 

10  Join  Server  2 to  installed  domain  (first  configure  a Server2  to  use  of 
new  DNS  on  serverl ). 

11  Log  on  to  Server  2 as  a member  of  the  Domain  Administrators  group. 

12  Install  MS  Exchange  server  2003  on  Server  2. 

13  Install  MS  Exchange  server  2003  SP1  on  Server  2. 

Step  2.  Deploy  Hosted  Messaging  and  Collaboration 

1 Log  on  to  Server  2 as  a member  of  the  Domain  Administrators  group. 

2 Install  the  MPS  (Microsoft  Provisioning  Service)  deployment  tool. 

1 . Quit  all  running  programs. 

2.  Open  command  prompt,  and  change  the  directory  to  Service 
Provisioning\DeploymentT  ool 

3.  To  install  the  Deployment  Tool  on  Server  2,  run  the  following  from  the  command 
prompt:  Deployment  Tool. msi 

Note:  If  you  are  not  installing  from  CD,  you  will  be  prompted  to  enter  a path  to  the 
root  directory  of  the  solution  media  source  files. 

4.  When  prompted  for  the  server  name  for  configuration  files,  enter  Error! 
Hyperlink  reference  not  valid.  2name>,  and  then  click  OK. 

5.  When  prompted  for  the  server  name  for  installation  files,  enter  Error!  Hyperlink 
reference  not  valid.  2name>,  and  then  click  OK. 

6.  In  the  confirm  configuration  dialog  box,  click  Yes  if  the  settings  are  correct,  or 
click  No  to  cancel. 

7.  In  the  Do  you  want  to  install  the  deployment  tool  to  the  local  computer?  dialog 
box,  click  Yes.  A shortcut  for  the  Deployment  Tool  will  be  added  to  the  desktop 
of  Server  2. 

8.  Restart  winbox  after  MPS  (Microsoft  Provisioning  Service)  deployment  tool  has 
been  installed. 

3 Create  an  MPS  SQL  Service  Account  for  MPS  Interaction  with  SQL- 
based  Servers 

Procedure  DWSPV.1 1 : To  create  a SQL  service  account  on  the  domain  controller 

1 . Log  on  to  WServerl  using  an  account  that  is  a member  of  the  domain 
administrators  group. 

2.  On  the  taskbar,  click  Start,  point  to  Administrative  Tools,  and  then  click  Active 
Directory  Users  and  Computers. 

3.  Expand  fabrikam.com  (domain). 

4.  Right-click  Users,  point  to  New,  and  then  click  User. 

5.  In  the  New  Object-User  dialog  box,  type  MPSSQLService  as  the  First  name  and 
the  User  logon  name,  and  then  click  Next. 
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6.  In  the  next  New  Object  - User  dialog  box,  clear  the  User  must  change  password 
at  next  logon  check  box.  Enter  the  password  (twice),  and  then  select  Password 
never  expires. 

7.  Click  Next.  Verify  the  information  you  have  entered,  and  then  click  Finish. 

4 Add  MPSSQLService  to  the  Local  Administrators  Group 

Procedure  DWSPV.12:  To  add  MPSSQLService  to  the  local  administrators  group 

1 . Log  on  to  \\Server2  as  a member  of  the  domain  administrators  group. 

2.  On  the  taskbar,  click  Start,  point  to  All  Programs,  then  to  Administrative  Tools, 
and  then  click  Computer  Management. 

3.  Expand  Local  Users  and  Groups,  and  then  click  Groups. 

4.  Double-click  Administrators. 

5.  Click  Add,  and  then  type  MPSSQLService.  Click  Check  Names  to  make  sure 
that  the  name  resolves,  and  then  click  OK. 

6.  Click  OK  to  close  the  Administrator  Properties  window. 

5 Install  the  MPF  (Microsoft  Provisioning  Framework)  Engine  and 

Database 

Procedure  DWSPV.20:  To  deploy  the  Core  Platform 

1 . Log  on  to  Wserver2  as  a member  of  the  enterprise  administrators  group.  Set  your 
screen  resolution  to  1024  x 768  to  properly  display  the  Provisioning  Deployment 
Tool  interface  when  you  start  it. 

2.  On  the  Wserver2  desktop,  double-click  the  shortcut  to  the  MPS  Deployment  Tool. 

3.  Click  the  Servers  tab,  and  then,  under  SQL  Servers,  click  Add. 

4.  In  the  Add  SQL  Server  dialog  box,  type  <Server  2 name>,  and  then  click  OK. 

5.  Under  MPS  Servers,  click  Add. 

6.  In  the  Add  Server  dialog  box,  type  the  name  of  the  MPF  Engine  server  as 
<Server  2 name>,  and  then  click  OK. 

7.  In  the  Requirements  Status  pane,  expand  Core  Platform,  expand  Initialize  Active 
Directory,  right-click  Native  Mode,  and  then  select  Confirm  irreversible  Native 
Mode  conversion.  In  the  Active  Directory /Native  Mode  dialog  box,  click  OK. 
Right-click  Native  Mode  and  then  select  Install. 

8.  Under  the  Initialize  Active  Directory  component,  right-click  List  Object  Mode,  and 
then  select  Install. 

9.  In  the  Requirements  Status  pane,  expand  Core  MPF  Install,  right-click  the  MPF 
Engine  component,  select  Install  on  Server,  and  then  click  <Server  2 name>.  The 
icon  next  to  the  MPF  Engine  component  changes  to  a silver  disk  to  indicate  that 
you  have  scheduled  the  installation  of  this  component. 

10.  In  the  Requirements  Status  pane, under  Core  MPF  Install,  expand  MPF  Config 
Database.  Right-click  SQL  not  assigned,  select  Install  on  SQL  Instance,  and 
then  click  <Server  2 name>. 

1 1 . Repeat  step  1 0 for  each  of  the  MPF  database  components: 

■ Resource  Manager  Database 
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■ MPF  Audit  Database 

■ MPF  Transaction  Database 

1 2.  In  the  Requirements  Status  pane,  under  Core  MPF  Install,  right-click  the  MPF 
Audit  and  Recovery  component,  point  to  Install  on  Server,  and  then  click  Add 
New  Server. 

1 3.  Right-click  the  MPF  Audit  and  Recovery  component,  point  to  Install  on  Server, 
and  then  click  Add  New  Server. 

14.  In  the  Requirements  Status  pane,  right-click  Core  Platform,  and  select  Install  all 
in  this  group. 

15.  If  prompted  with  the  Confirm  Install  on  Dependents  dialog  box,  review  the  list  of 
actions  to  be  performed,  and  click  OK. 

16.  Click  Start  Deployment  to  start  the  installation  of  the  MPF  Engine,  databases, 
and  namespaces/providers  on  the  server. 

1 7.  Monitor  the  deployment  session  on  the  Install  Details  tab. 

18.  When  the  deployment  is  complete,  on  the  Action  History  tab,  click  View  Details 
to  review  events. 

19.  Close  the  Provisioning  Deployment  Tool. 

6 Install  the  Plans  Database 

Procedure  DWSPV.21 : To  deploy  the  Hosting  Platform 

1 . In  the  MPS  Deployment  Tool,  in  the  Requirements  Status  pane,  expand  Hosting 
Platform,  expand  Plosted  PlansDatabase,  then  expand  Plans  Database. 

2.  Right-click  Server  not  assigned,  click  Install  on  Server,  then  click  <Server  2 name>. 

3.  Under  Plans  Database,  right-click  <Server  2 name>  and  click  Select  SQL  instance. 

4.  In  the  Select  SQL  Server  dialog  box,  type  <Server  2 name>  and  then  click  OK. 

5.  In  the  Requirements  Status  pane,  below  Hosting  Platform,  expand  Initialize 
Default  Services. 

6.  Right-click  Initialize  Active  Directory  for  Hosting,  then  select  Set  procedure 
parameters. 

7.  When  prompted  for  the  name  of  the  hosting  organization,  accept  the  default  of 
Hosting  and  then  click  OK. 

8.  In  the  Requirements  Status  pane,  right-click  Hosting  Platform,  and  select  Install 
all  in  this  group. 

9.  Click  Start  Deployment  to  start  the  installation  of  the  Plans  Database  and 
Hosting  Platform  Service  Components. 

1 0.  Monitor  the  deployment  session  on  the  Install  Details  tab. 

7 Install  the  MPS  Web  Services  on  Server  2 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  right-click  Web  Service,  select  Install  on 
Server,  and  then  select  <Server  2 name>. 

3.  Under  Business  Web  Service-><Server  2 name>,  right-click  on  the  New  Virtual 
Directory  box,  enter  MPSWS,  and  then  click  OK. 
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Note:  After  you  assign  the  Web  service  and  input  the  virtual  directory  name,  the 

MPF  Client  will  automatically  be  assigned  for  installation  on  Server  2. 

4.  Click  Start  Deployment. 

5.  When  the  deployment  completes,  click  OK,  and  then  quit  the  MPS  Deployment 
Tool. 

8 Install  Resource  Manager  Web  Client  on  Server  2 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  right-click  Web  Services->Resource  Manager 
Web  Client,  select  Install  on  Server,  and  then  select  <Server  2 name>. 

3.  In  the  New  Virtual  Directory  box,  enter  ResourceManagerWebClient,  and  then 
click  OK. 

4.  Click  Start  Deployment. 

5.  When  the  deployment  completes,  click  OK,  and  then  quit  the  MPS  Deployment 
Tool. 

9 Initialize  Hosted  Exchange  Provisioning  Namespaces 

1.  Run  the  MPS  Deployment  Tool. 

2.  In  the  Requirements  Status  pane,  expand  Hosted  Exchange. 

3.  Expand  Exchange  Platform. 

4.  Right-click  Hosted  Exchange  Namespace,  and  then  click  Execute.  Initialize 
Hosted  Exchange  Namespace.  Make  sure  to  check  if  Exchange  organization  is 
being  set  correctly. 

5.  Click  Start  Deployment. 

10  Configure  the  MPFServiceAccts  Group  As  Exchange  Full 

Administrator 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  right-click  the  top  node  where  the  name  of  your  Exchange 
organization  is  displayed,  and  then  click  Delegate  control  to  start  the  wizard. 

3.  Click  Next,  click  Add,  click  Browse,  select  MPFServiceAccts  from  the  list,  and 
then  click  OK. 

4.  On  the  drop-down  menu,  click  Exchange  Full  Administrator,  click  OK,  click  Next, 
and  then  click  Finish.  If  prompted  with  a security  dialog  box,  click  OK. 

5.  Initialize  Hosted  Exchange  Provisioning  Platform. 

6.  In  this  procedure  you  will  initialize  your  environment  for  Hosted  Exchange 
provisioning. 

11  Configure  the  Microsoft  Provisioning  System  Server  for  Hosted 

Exchange 

Procedure  DP. 3:  To  initialize  Hosted  Exchange  provisioning  namespaces 

1 . Log  on  to  <Server  2 name>  as  a member  of  the  Domain  Administrators  group. 

2.  Run  the  MPS  Deployment  Tool. 

3.  Expand  Hosted  Exchange. 
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4.  Expand  Exchange  Platform. 

5.  Right-click  Native  Mode,  and  then  click  "Confirm  irreversible  Native  Mode 
conversion". 

6.  At  the  Microsoft  Exchange/Native  Mode  dialog  box,  click  OK. 

7.  Right-click  Exchange  Platform,  and  then  select  Install  all  in  this  group. 

8.  Click  Start  Deployment. 

Check  the  log  information  at  the  bottom  of  the  Configuration  Wizard  screen  to 
verify  that  the  configuration  was  successfully  set. 

12  Configure  the  MPSExchangeAccts  Group  As  Exchange  Full 
Administrator 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  right-click  the  top  node  where  the  name  of  your  Exchange 
organization  is  displayed,  and  then  click  Delegate  control  to  start  the  wizard. 

3.  Click  Next,  click  Add,  click  Browse,  select  MPSExchangeAccts  from  the  list,  and 
then  click  OK. 

4.  On  the  drop-down  menu,  click  Exchange  Full  Administrator,  click  OK,  click  Next, 
and  then  click  Finish.  If  prompted  with  a security  dialog  box,  click  OK. 

13  Configure  the  All  Address  Lists  Container 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  click  the  Recipients  node,  expand  the  tree. 

3.  Right-click  the  All  Address  Lists  and  select  Properties. 

4.  Click  the  Security  tab,  click  Advanced,  and  then  click  Add  under  Permissions. 

5.  In  the  Name  text  box,  type  MPSExchangeAccts,  and  then  click  OK. 

6.  In  the  Apply  onto  list,  select  This  object  and  subcontainers. 

7.  In  the  Permissions  list,  click  Full  Control. 

8.  Click  OK  three  times. 

14  Add  the  MPSExchangeAccts  Group  to  Local  Administrators  Group 

15  Create  Mailbox  Stores  for  Hosted  Exchange  (only  fro  enterprise 
exchange) 

1 . Click  Start,  point  to  Programs,  point  to  Microsoft  Exchange,  and  then  click 
System  Manager. 

2.  In  the  console  tree,  expand  Servers,  then  expand  <Exchange  Server>,  and  then 
expand  First  Storage  Group. 

3.  Create  any  appropriate  mailbox  stores  will  be  used  as  a Business  Mailstores. 

16  Initialize  Resource  Management 

1.  Restat  IIS  on  server2 

2.  Launch  Internet  Explorer,  and  go  to 

http : / / 1 ocal ho s t /Re sourceManagerWebClient/QueryRe sources . as 
px. 
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3.  When  prompted  for  Username  and  Password,  log  in  as  <domain 
r?a/77e>\Administrator. 

4.  Enter  <Server  1 fullname>  in  the  Preferred  Domain  Controller  text  box.  Click 
Submit. 

5.  In  the  left  pane,  click  Exchange  Resource  Manager.  Then,  select  the  Business 
Mailstores  tab. 

6.  Add  Business  Mailstore  resources. 

7.  Important:  The  <shared>  value  should  always  be  set  to  1 for  Business  mail  stores 

8.  In  the  left  pane,  click  Exchange  Resource  Manager.  Then,  select  the  Public 
Stores  tab. 

9.  Under  Publicstores,  click  Add  New  Resource. 

10.  Add  Public  Store  resources  (Server  and  Public  Store  names  you  can  find  in 
Exchange  System  Manager). 

1 1 . In  the  left  pane,  click  Exchange  Resource  Manager,  and  then,  select  the  OAB 
Servers  tab. 

12.  Under  OAB  Servers,  click  Add  New  Resource. 

13.  Add  OAB  Server  resources. 

17  Install  the  Hosted  Exchange  Offline  Address  Book  (OAB)  Update 

Batch  Application  (on  page  289) 

18  Deploy  the  MPS  Sample  Web  Client 

1 . Run  SetupMPSSampleWeb.msi  from  the  Windows-based  Hosting  distribution 
media  in  the  \Sampies\Provisioning\MPSSampieWeb  directory. 

2.  On  the  MPPSSampleWeb  Setup  Wizard  Welcome  page,  click  Next. 

3.  On  the  Select  Installation  Address  page,  accept  the  default  Virtual  Directory 
(MPSSampleWeb)  and  Port  (80),  and  then  click  Next. 

4.  On  the  Confirm  Installation  page,  click  Next. 

5.  On  the  Installation  Complete  page,  click  Close. 

6.  Open  the  Internet  Information  Services  (IIS)  Manager,  and  then  expand  the 
default  Web  site. 

7.  Right-click  MPSSampleWeb,  and  then  select  Properties. 

8.  Click  the  Directory  Security  tab,  and  then,  under  Authentication  and  access 
control,  click  Edit. 

9.  Clear  the  Enable  anonymous  access  check  box. 

10.  Ensure  that  the  Integrated  Windows  Authentication  check  box  is  cleared. 

1 1 . Select  the  Basic  authentication  check  box,  and  then,  in  the  warning  dialog  box, 
click  Yes. 

1 2.  Enter  a backslash  “\”  in  the  default  domain  field. 

1 3.  Click  OK,  and  then  click  OK  again. 

14.  Close  the  IIS  Manager  window. 
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15.  Edit  the  Web.Config  file  in  the  root  directory  of  the  MPS  Sample  Web  Client 
(usually  \inetpub\wwwroot\MPS  Sample  Web).  Set  the  following  preferredDC 
and  Def  aultNamingContext  key  values  to  your  preferred  domain  controller 
and  default  naming  context.  For  example: 

<appSettings> 

<add  key="pref erredDC"  value="Server  1 full  name>"/> 

<add  key=" Def aultNamingContext" 

Value="DC=domain  name  parti , DC=domain  name  part2"/> 
example  test.ts.com  Value="DC=test, DC=ts, DC=com" 

19  Disable  the  EventSink: 

1.  Goto  C:\Program  Files\Microsoft  Hosting\Provisioning\MPSWS\ 

and  open  file  web.config. 

2.  Find  the  <add  key="EnabieEventsink"  vaiue="i"/>  string  and  change 
value  to  0 (<add  key="EnableEventSink"  value="0"/>) 

3.  Save  changes. 

It  will  allow  creating  Exchange  Recipient  Policy  for  new  SMTP  domains. 

Step  3.  Install  WS  Exchange  Provider  Adapter 
Namespace 

WS  Exchange  Provider  Adapter  Namespace  (WS  stands  for  "Web  service")  provides 
communication  between  Parallels  Pi-Sphere  and  MS  Exchange  provider  via  FITTP  in 
order  to  manage  MS  Exchange  hosting  in  Parallels  Pi-Sphere  CP. 

1 Download  WS  Exchange  Provider  Adapter  Namespace  installation: 
http://hsphere.parallels.com/downloads/wsexchanqeprovider.msi. 

2 Run  the  downloaded  MSI  file  and  follow  the  installation  instructions. 

Step  4.  Create  Reseller  Organization  Unit 

Create  reseller  organization  unit  under  which  Parallels  Pi-Sphere  users  signed  up  for 
MS  Exhange  plans  will  be  hosted.  On  Server  2: 

1 In  Internet  Explorer,  go  to  http://localhost/MPSSampleWeb 

2 When  prompted,  log  on  as  Domain  Administrator. 

3 Leave  the  Current  Reseller  and  Current  Customer  fields  empty. 

4 Select  the  General  tab. 

5 In  the  left-hand  pane,  click  Create  a Reseller  Organization. 

6 Enter  information  about  the  organization  in  the  appropriate  boxes  on 
the  Create  Reseller  Org  page 

7 Click  Submit  Request. 

8 When  the  request  completes,  you  can  review  the  XML  response  at  the 
bottom  of  the  page. 
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After  that,  you  can  proceed  to  configuring  Microsoft  Provisioning  Framework  in  admin 
CP.  This  is  described  in  MS  Exchange  section  of  Parallels  H-Sphere  Service 
Administrator  Guide. 

That's  how  the  organization  unit  may  look  like  when  it  is  created  and  used  for  Parallels 
H-Sphere  hosting: 


| 4|  Active  Directory  Users  and  Computers 
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In  the  above  screenshot,  Organizationl  is  the  reseller  organization  unit,  and  its 
organization  units  like  exchange  are  Parallels  H-Sphere  user  accounts  with  emails  and 
distribution  lists. 
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Calculating  Winbox  Traffic 

In  Parallels  H-Spherethe  system  writes  winbox  traffic  data  to  XML  logfiles: 

■ YYYY-MM-DD . web  . xml  - http  traffic, 

■ yyyy-mm-dd  . f tpg . xml  - guest  ftp  traffic, 

■ yyyy-mm-dd  . f tpa . xml  - anonymous  ftp  traffic. 

Example: 

<TrafficEntries> 

<DailyEntries  Date="2005-10-28"  Type="web"> 

<Entry  Name="domainl . wincp241 . test"> 

<Incoming>7782</ Incoming> 

<Outgoing>3 90  60</ Outgo ing> 

<Hits>15</Hits> 

<HtmlHits>8</HtmlHits> 

</Entry> 

<Entry  Name="domain2 . wincp241 . test"> 

<Incoming>34  93</ Incoming> 

<Outgoing>3854  9</ Outgoing> 

<Hits>8</Hits> 

<HtmlHits>2</HtmlHits> 

</Entry> 

</DailyEntries> 

</TrafficEntries> 

These  xml  files  are  saved  to  the  C : \HSphere  . NET\data\services\traf  f ic\ 

directory.  Once  a day  TrafficLoader  (on  page  36)  parses  these  files  using  SOAP  and 

writes  statistic  data  into  the  translog  table  of  the  Parallels  H-Sphere  system 

database.  After  that  these  files  are  deleted  and  created  anew  on  the  next  day. 
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Creating  Mail  Plan  on  MPS  Server 

This  document  is  an  example  of  how  to  create  a new  Mail  Plan  on  MPS  Server 
(Server2,  i.e  MS  Exchange  Server ). 

> To  create  mail  plan  on  MPS  Server: 

1 Remove  the  read-only  attribute  and  then  edit 

<installdir>: \ Program  Files\Microsoft 
Hos ting\ Provi sioning\ Sample s \Hos ted  Exchange 
Namespace\CreateMailboxPlan  . XML.  The  following  example 
shows  the  XML  in  the  shipped  version  of  this  file: 

< request  xml ns :xsl="http: // www .w3.org/ 1 999/XSL/Transf orm"> 
<procedure  xmlns : xsl= ' http : / /www .w3.org/ 1 999/XSL/Transf orm ' > 
<execute  namespace="Hosted  Exchange" 
procedure="CreateMailboxPlan"  impersonate^'  1 "> 

<executeData> 

<planName>PopMail</planName> 

<planDescription>P0P3  Mail</planDescription> 

<planCategories> 

<category> 

<categoryName>HeBusiness</ categoryName> 

</ category> 

<category> 

<categoryName>HeConsumer</ categoryName> 

</ category> 

</planCategories> 

<planFeatures> 

<f eature> 

<f eatureName>OWA</ f eatureName> 

<f eatureDescription>Outlook  Web  Access 
DisabledC/ f eatureDescription> 

<f eatureValue>l</ f eatureValue> 

</ f eature> 

<f eature> 

<f eatureName>IMAP</ featureName> 

<f eatureDescription>IMAP  Access  Disabled</f eatureDescription> 
<f eatureValue>l</ f eatureValue> 

</ f eature> 

<f eature> 

<f eatureName>POP</ f eatureName> 

<f eatureDescription>POP  Access  Enabled</f eatureDescription> 

<f eatureValue>0</ f eatureValue> 

</ f eature> 

<f eature> 

<f eatureName>MailboxSize</ f eatureName> 

<f eatureDescription>Mailbox  size  in 
kilobytesc/ f eatureDescription> 

<f eatureValue>l 0000c/ f eatureValue> 
<unitDescription>kb</unitDescription> 

</ f eature> 
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</planFeaturesk 

<pref erredDomainController>AD01 . fabrikam. com</preferredDomainC 
ontroller> 

</executeData> 

<after  source="executeData"  destination="data"  mode="merge" /> 
</execute> 

</procedure> 

</ request> 

2 Edit  the  <planName>  element  as  follows: 

<planName>SimpleMail</planName> 

3 Edit  the  <planDescription>  element  this  way: 

<planDescription>Basic  POP3  Mailbox</planDescription> 

4 Edit  the  <preferredDomainController>  value,  where 
AD01  .fabrikam.com  is  the  full  name  of  Active  Directory  domain 
controller  server. 

5 The  edited  file  should  now  look  like  the  following: 

< request  xml ns :xsl="http: // www .w3.org/ 1 999/XSL/Transf orm"> 
<procedure  xml ns : xsl= ' http : / /www .w3.org/ 1 999/XSL/Transf orm ' > 
<execute  namespace="Hosted  Exchange" 
procedure="CreateMailboxPlan"  impersonate^'  1 "> 

<executeData> 

<planName>SimpleMail</planName> 

<planDescription>Basic  POP3  Mailbox</planDescription> 
<planCategories> 

<category> 

<categoryName>HeBusiness</ categoryName> 

</ category> 

<category> 

<categoryName>HeConsumer</ categoryName> 

</ category> 

</planCategories> 

<planFeatures> 

<f eature> 

<f eatureName>OWA</ f eatureName> 

<f eatureDescription>Outlook  Web  Access 
Disabledc/ f eatureDescription> 

<f eatureValue>l</ f eatureValue> 

</ f eature> 

<f eature> 

<f eatureName>IMAP</ featureName> 

<f eatureDescriptionkIMAP  Access  Disabled</f eatureDescriptionk 
<f  eatureValuekK/ f eatureValuek 
</ f eaturek 
<f eaturek 

<f eatureNamekPOP</ f eatureNamek 

<f eatureDescriptionkPOP  Access  Enabled</f eatureDescriptionk 
<f eatureValuekCK/ f eatureValuek 
</ f eaturek 
<f eaturek 

<f eatureNamekMailboxSizeC/ f eatureNamek 
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<f eatureDescription>Mailbox  size  in 
kilobytes</ f eatureDescription> 

<f eatureValue>l 0000</ f eatureValue> 
<unitDescription>kb</unitDescription> 

</ f eature> 

</planFeatures> 

<pref erredDomainController>AD01 . fabrikam. com</preferredDomainC 
ontroller> 

</executeData> 

<after  source="executeData"  destination="data"  mode="merge"/> 
</execute> 

</procedure> 

</request> 

6 Save  the  edited  file  in  the  in  the  <instaiidir>:  \ Program 
Files \Microsoft  Hos ting \Provis ioning\ Sample s \ Hosted 
Exchange  Namespace \ directory  as  CreateSimpleMailPlan.xml. 

7 From  a command  prompt  in  the  <installdir>:  \ Program 
Files \Microsoft  Hos ting \Provis ioning\ Sample s \ Hos ted 
Exchange  Namespace\  directory,  execute  provtest 
CreateSimpleMailPlan.XML  (ProvTest.exe  is  located  in  C:\Program 
Fiies\Microsoft  Provisioning\Too!s). 

You  now  have  a mailbox  plan  called  SimpleMail,  which  enables  a 10  MB  mailbox  for 
use  by  POP3  clients.  This  plan  will  show  up  as  available  to  add  to  new  organizations. 
Also  you  can  edit  other  features  like  MailboxSize. 

By  default,  MPS  sets  mailbox  size  using  the  following  scheme: 

<s/'ze>  - Mailbox  size  in  kilobytes  (equivalent  to  ProhibitSendQuota) 

<warningQuota>  - the  default  one  is  90  percent  of  size 
<prohibitSendAndReceiveQuota>  - the  default  one  is  500  percent  of  size 

So  if  you  create  a mailbox  with  the  size  of  100Mb,  the  parameters  will  be  as  follows: 

■ Warning  Quota  - 90MB 

■ Prohibit  Send  Quota  - 1 00  MB 

■ Prohibit  Send  And  Receive  Quota  - 500MB. 

Note:  if  the  size  of  mailbox  is  ~2GB  (maximum),  the 

<prohibitSendAndReceiveQuota>  parameter  will  have  the  maximum  possible 
value  (not  5x2GB). 


Read  more  about  Mailbox  store  prohibit  send  and  receive  limits  of  mailboxes  at 
Microsoft  documentation:  http://technet.microsoft.com/en-us/library/79f14549-6c7b- 
4073-8628-b93654f3659e.aspx. 
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Microsoft  SQL,  like  other  commercial  third  party  products,  is  purchased  and  installed 
separately  from  Parallels  H-Sphere. 

Microsoft  SQL  Server  is  a fully  Web-enabled  database  with  the  ability  to  query  the 
database  through  a browser  and  rich  Extensible  Markup  Language  (XML)  support.  In 
addition,  Microsoft  SQL  Server  holds  benchmark  records  for  scalability  and  reliability, 
both  of  which  are  crucial  for  the  success  of  an  enterprise  database. 

For  extensive  coverage  of  Microsoft  SQL  Server,  please  refer  to 
http://www.microsoft.com/sgl/default.asp. 

In  this  chapter: 


Installing  Microsoft  SQL  2000  Server 31 1 

Installing  Microsoft  SQL  2005  Server 312 

Moving  MS  SQL  Databases  Across  Servers 313 

Moving  MS  SQL  Databases  to  a New  Location 314 
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Installing  Microsoft  SQL  2000  Server 

This  document  explains  how  to  install  MS  SQL  database  software  and  integrate  it  with 
the  Parallels  H-Sphere  system. 

Parallels  H-Sphere  supports  both  Microsoft  SQL  7.0  and  Microsoft  SQL  2000  servers. 

MS  SQL  server  can  be  installed  on  an  Parallels  H-Sphere  Windows  server.  This 
means,  the  server  must  have  Parallels  H-Sphere  Windows  software  installed  and  be 
added  to  the  Parallels  H-Sphere  configuration. 

> To  install  MS  SQL  server: 

1 Buy  a License  package. 

2 Install  MS  SQL  server  following  the  directions  of  the  installation 
wizard. 

3 Configure  Parallels  H-Sphere  connection  settings  to  work  with  MS 
SQL  server. 

■ If  you  already  have  MS  SQL  server  and  are  installing  Parallels  H-Sphere,  follow 
Parallels  H-Sphere  Winbox  Installation  Guide. 

■ If  Parallels  H-Sphere  was  installed  earlier  and  you  are  adding  MS  SQL  server  to 
it,  set  the  following  three  values  for  MS  SQL  Server  variables  in  the 
<HSPHERE_HOME_DIR> / script/conf . inc  file  on  the  Windows  server: 

■ mssqIServer  = IP  of  the  MS  SQL  server  if  it  works  through  TCP/IP  or  the 
server  name  if  MS  SQL  uses  pipe  connection. 

■ mssqlHSLogin  = a login  with  system  adminitrator  privileges  for  the  MS  SQL 
server.  You  can  create  this  login  by  means  of  MS  SQL  Enterprise  Manager. 

If  there  is  any  login  registered  earlier  with  the  same  privileges,  you  can  use 
it,  too. 

■ mssqlHSPasswd  = password  for  this  login. 

4 Go  to  SQL  Server  Properties  ->  Security  and  choose  SQL  Server 
Authentication  and  Windows  Authentication  to  allow  Parallels  H- 
Sphere  and  your  customers  to  access  MS  SQL  server  remotely. 
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Installing  Microsoft  SQL  2005  Server 

This  document  explains  how  to  install  MS  SQL  database  software  and  integrate  it  with 
the  Parallels  H-Sphere  system. 

Parallels  H-Sphere  2.5.0  and  higher  supports  Microsoft  SQL  Server  2005 
(http://www.microsoft.com/technet/prodtechnol/sgl/2005/default.mspx). 

MS  SQL  server  can  be  installed  on  Parallels  H-Sphere  Windows  server.  This  means 
the  server  must  have  Parallels  H-Sphere  Windows  software  installed  and  be  added  to 
the  Parallels  H-Sphere  configuration. 

To  add  MS  SQL  2005  to  winbox  with  Parallels  H-Sphere  installed: 

1 Install  ASP.NET  2.0  and  check  the  version  of  ASP.NET. 

Rootver  must  be  2.0.XXXX,  not  1.1.XXXX  in  the  registry 

HKLM/ Software /Microsoft /ASP .NET. 

If  RootVer  is  1.1.XXXX: 

■ Goto  C : \Windows\Microsof  t . NET\Framework\v2 . 0 . 5xx\  through 
command  line 

■ Run  from  command  line: 
aspnet_regiis  -r 

■ Restart  IIS  : 
iisreset  /restart 

2 Install  MS  SQL  server  following  the  directions  of  the  installation 
wizard.  If  you  installed  SQL  2005,  you  should  also  install  SQL  Server 
Management  Studio  Express. 

3 In  SQL  Server  Managment  Studio  Express  create  login  with  system 
administrator  privileges  for  the  MS  SQL  server.  As  a rule,  login  'sa'  is 
used. 

4 Configure  Parallels  H-Sphere  connection  settings  to  work  with  MS 
SQL  server: 

Note:  Parallels  H-Sphere  3.0  + uses  Windows  authentication  method  to  connect  to 
MSSQL  server.  Therefore  MSSQL  server  should  be  installed  locally  on  the  same 
server  with  Parallels  H-  Sphere. 

Go  to  /hsphere  . net/bin/hsphere  . conf  ig  file  and  make  Sure  the 
name_of_your_sql_server  is  set  correctly  in: 

prop  name=" server"  value="NAME_OF_YOUR_SQL_SERVER" 
description="MSSQL  server  name  or  IP" 

5 Go  to  SQLServer  Properties  ->  Security.  Chose  SQL  Server 
Authentication  and  Windows  Authentication  to  allow  Parallels  H- 
Sphere  and  your  customers  to  access  MS  SQL  server  remotely. 
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6 Make  sure  that  MS  SQL  server  IP  set  as  a logical  server  IP  in  the 

E. Manager  menu  is  set  in  Start  ->  Programs  ->  MSSQL  2005  Server  -> 
Configuration  Tools  ->  SQL  Server  Configuration  Manager  ->  SQL 
Server  Network  Configuration  ->  Protocols  for  MSSQLSERVER  -> 
TCP/IP(enabled)  ->  Properties  ->  IP  Addresses  tab.  Make  sure  this  IP 
is  there  with  Active  and  Enabled  set  to  Yes. 

7 In  your  CP  add  MS  SQL  server  group  to  the  physical  winboxes  with 
MS  SQL  installed. 

8 Add  logical  MS  SQL  servers  in  CP  and  add  IP  addresses  for  it. 

9 On  winboxes  run  the  following  commands: 

net  stop  hsphere 
net  start  hsphere 

10  Turn  on  MS  SQL  servers  in  the  user's  Plan  Edit  Wizard.  After  that,  try 
creating  MS  SQL  databases  from  user's  CP. 


Moving  MS  SQL  Databases  Across 
Servers 

> To  move  the  databases  from  one  MS  SQL  server  to  another: 

1 Install  the  new  MS  SQL  server,  keeping  the  same  path  to  databases 
as  for  the  old  server.  That  means,  databases  on  the  new  server 
should  be  located  on  the  same  disc  and  necessarily  in  the  same 
directory  as  for  the  old  server.  For  example,  on  the  old  server  data  is 
located  on  d:  \mssqi\data\,  so  the  data  on  the  new  server  should 
be  located  in  the  same  directory. 

2 Stop  the  new  MS  SQL  server. 

3 Copy  all  MS  SQL  database  files  including  the  "master"  database 
which  keeps  all  logins  information  and  other  necessary  information. 

Important:  All  database  files  should  be  put  into  the  same  directory  as  for  the  old 
server. 

4 Start  the  new  MS  SQL  server. 

5 Change  the  MS  SQL  logical  server  IP  to  the  new  MS  SQL  server  IP  in 
the  Control  Panel. 

6 All  resellers  should  reconfigure  MS  SQL  server  aliases  to  use  the  new 
IP  for  the  MS  SQL  server. 
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Moving  MS  SQL  Databases  to  a New 
Location 


This  document  describes  how  to  change  the  location  of  the  data  and  log  files  for  any 
MS  SQL  database.  There  are  two  ways  to  move  MS  SQL  databases: 

Method  1 

(preferable) 

1 Create  new  MS  SQL  data  location  (e  : \MSSQL\data\) 

2 Stop  MS  SQL  server 

3 Move  all  databases  to  a new  location  (move  *.mdf  and  *.ldf  files) 

4 Create  junction  link  between  old  and  new  MS  SQL  data  folders.  This 
can  be  done  with  Sysinternals  Junction 

(http://download.hsphere.parallels.com/shiv/WinBox/linkmaqic.exe)  or 

any  other  utility  of  this  kind 

5 Start  MS  SQL  server 

In  case  you  have  some  databases  with  different  from  default  locations: 

1 Detach  these  databases 

2 Copy  these  databases  from  old  location  to  a new  location 

3 Attach  these  databases  from  a new  location 
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Method  2 

1 Go  to  MS  SQL  Enterprise  Manager 

2 Choose  the  MS  SQL  server  Properties  option.  For  this,  go  to  Expand  SQL 
Server  Group  > MS  SQL  server  <SQL  Server_Name> 
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3 On  the  Database  Settings  tab,  change  New  database  location  and  set 
the  path  to: 

■ Default  data  directory,  i.e.  a new  logical  disk  (e  : \mssql\data\) 

■ Default  log  directory  (e  : \mssql\data\) 


4 Create  the  following  folder  E:\mssql\data\ 

5 Set  the  same  NTFS  permissions  as  in  the  folder  [drive]  : \Program 
Files\Microsof t SQL\Server\MSSQL\DATA  (the  path  where 
DB's  are  located). 

6 Go  to  MS  SQL  Enterprise  Manager  > Databases  and  right  click  on  the 
Necessary  database  > All  tasks  > Detach  Database  with  the  option  Update  statistics 
prior  detach.  Make  sure  to  check  database  and  database  log  files 
locations  before  detaching  a database. 
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9 Put  the  path  to  the  necessary  database  (e  : \mssql\data\)  and 
select  hsadmin  in  Specify  database  owner  field. 


10  Repeat  steps  6-8  for  the  rest  of  databases. 


All  necessary  information  can  be  found  in  MS  SQL  documentation 
(http://www.microsoft.com/sql/default.mspx). 
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Virtual  Private  Servers 


Parallels  H-Sphere  VPS  feature  integrates  virtual  private  server  hosting  into  H-Sphere. 
Install  H-Sphere  VPS  software  on  a separate  physical  box  and  add  this  box  to  your  H- 
Sphere  cluster.  This  software  is  then  identified  as  a logical  VPS  server  and  run  by  a 
number  of  packages  that  may  vary  depending  on  your  operating  system 

Once  installation  is  performed  and  VPS  hosting  is  configured  in  H-Sphere,  users  who 
signup  to  VPS  plans  get  a virtual  server  in  their  use  and  a user  CP  interface  from  which 
to  configure  servers.  The  number  of  virtual  servers  per  your  physical  box  is  limited  by 
the  amount  of  system  resources  consumed  by  them  and  hardware  parameters  of  the 
VPS  host  server. 

Since  Parallels  H-Sphere  virtual  private  servers  are  logically  separate  boxes,  their 
network  interfaces  must  be  configured  identically  to  separate  boxes  in  your  Parallels  H- 
Sphere  cluster.  Even  though  the  main  server  has  only  one  physical  network  adapter, 
the  kernel  emulates  separate  logical  network  adapters  for  each  virtual  private  server. 
Hence,  it  is  NOT  correct  to  treat  VPS  IPs  as  aliases  to  the  main  server  IP. 

Interaction  with  the  main  server.  Logically  separate,  the  main  server  and  virtual 
private  servers  don't  communicate  with  each  other  directly  or  interact  any  differently 
from  regular  servers.  Virtual  private  servers  don't  know  anything  about  their  'parent', 
they  don't  even  know  about  their  virtual  nature! 

Configuring  IPs.  VPS  IPs  are  set  up  automatically  and  are  registered  in  the  settings  of 
the  virtual  private  servers,  not  the  main  server.  DON'T  configure  virtual  private  server 
IPs  in  the  main  server  settings. 

Adding  or  Changing  IPs.  VPS  IPs  or  netmasks  can  be  added  or  changed  only 
through  the  Control  Panel.  This  can't  be  done  by  editing  the  settings  of  the  virtual 
private  servers. 

VPS  Gateway.  Virtual  private  servers  should  use  the  gateway  of  the  main  server  only  if 
they  belong  to  its  subnet.  If  placed  in  different  subnets,  they  must  be  given  different 
gateways. 


Configuration  Parameters 

The  default  VPS  configuration  file  is  /hsphere/local/ conf  ig/vserver/vps  . cfg. 


WARNING:  1 . Do  not  change  location  of  the  configuration  file! 

2.  It  is  strongly  recommended  not  to  make  changes  to  the  configuration  file  manually! 


If  you  need  to  set  parameters  to  the  configuration  file,  run  VPS  configuration  (on  page 
322)  script  (/hsphere/ shared/ scripts/vps-conf igure  .pi). 
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See  also  configuration  parameters  (on  page  344)  set  in  the  VPS  configuration  file. 

Template  configuration  files  are  located  in  $hsinstallpkg  (Default: 

/hsphere/ local/  conf  ig/vserver/<your  OS  code>/) 

where  <YourOS  code>\ 

RH73  - Red  Hat  Linux  release  7.3 

RHES3  - Red  Hat  Enterprise  Linux  ES  release  3 

RHAS3  - Red  Hat  Enterprise  Linux  AS  release  3 

RHWS3  - Red  Hat  Enterprise  Linux  WS  release  3 

WBEL3  - White  Box  Enterprise  Linux  release  3 

CentOS3  - CentOS  release  3 

rpm_base . cf  g - base  and  core  of  Linux 

rpm  development-tools . cfg  - Development  Tools 
rpm  dns-server . cfg  - DNS  Name  Server 
rpm  ftp-server . cfg  - FTP  Server 
rpm  kernei-vps . cfg  - kernel  emulator  for  VPS 
rpm  mail-server  . cfg  - Mail  Server 
rpm  mysql-server . cf g - MySQL  Database 
rpm  news-server  . cfg  - News  Server 
rpm_peri-fuii . cfg  - Perl  programing  language  modules 
rpm_pgsqi-server . cf g - Postgresql  SQL  Database 
rpm_quota  . cfg  - quota  tools  for  VPS 
rpm  samba-server . cfg  - Windows  File  Server 
rpm_system-toois . cfg  - System  Tools 
rpm  web-server . cfg  - Web  Server 
VPS  box  configuration  files  located  in  $vpsconfigs  (Default: 

/hsphere /local/  conf  ig/vserver/): 

vps . cfg  - the  main  configuration  file  for  all  Virtual  Private  Servers. 

vps . cf g . bak  - the  main  configuration  file  backup. 

vps . cfg . default  - default  configuration  for  all  Virtual  Private  Servers. 

vps . list  - the  list  of  all  known  VPS  and  the  list  of  Virtual  Private  Servers 
scheduled  for  removal. 


In  this  chapter: 
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VPS  Scripts 

Parallels  H-Sphere  VPS  is  a set  of  scripts  that  serve  as  the  backend  for  advanced  VPS 
management  via  Parallels  H-Sphere  CP  but  they  can  also  run  from  the  command-line 
mode.  The  latter  is  the  subject  of  this  section. 

All  VPS  scripts  are  located  in  the  $vpsscripts  directory  (Default: 

/hsphere/ shared/ scripts). 

Cron  scripts  are  located  in  the  $vPSSCRiPTS/cron  (Default: 

/hsphere/ shared/ scripts/ cron). 


In  this  section: 


Perl  Modules  Used  by  VPS  Scripts 322 

VPS  Configuration 322 

Create  VPS 323 

Migrate  VPS 324 

Delete  VPS 325 

VPS  Cron  Scripts 326 

VPS  Configuration  Scripts 329 

View  List  of  Installed  VPS's 332 

Install/Uninstall  Additional  Packages 332 

Check  VPS  Files  for  Changes 334 

VPS  IP  Migration  Tool 335 

VPS  Network  Configuration  Tools 336 

Device  Management 338 


322  Virtual  Private  Servers 


Perl  Modules  Used  by  VPS  Scripts 


Note:  We  provide  the  hsphere-vps  package  only  for:  Red  Hat  Linux  7.3  with  Perl  5.6.1 
installed. 

Red  Hat  Enterprise  Linux  release  3,  CentOS  3.x,  White  Box  Enterprise  Linux  release  3 
with  Perl  5.8.0  installed. 


If  you  wish  to  install  this  package  with  other  versions  of  Perl,  you  need  to  build  your 
own  Parallels  H-Sphere  VPS  binaries. 

Perl  modules: 

Red  Hat  Linux  7.3:  Perl  v5.6.1  modules  are  installed  in 

[/usr/lib/perl5/ site_perl/5 .6.1 /VServer/ ] 

Red  Hat  Enterprise  Linux  release  3,  CentOS  3.x,  White  Box  Enterprise  Linux  release  3: 
Perl  v5.8.0  modules  are  installed  in 

[/usr/lib/perl5/ site_perl/5 . 8 . 0 /VServer] 

Addon . pm 
Admin . pm 
Net . pm 
Util . pm 
Vars . pm 
Vrpm.pm 

VPS  Configuration 

Enter  the  $vpsscripts  directory  (Default:  /hsphere/shared/scripts)  to  run  the 
vps_configure.pl  script. 

SYNTAX: 

. /vps-configure .pi  [-d|-r|-h] 

OPTIONS: 

— defaults  | -d  load  default  settings 

--restore  | -r  restore  settings  you  made  before 

— help  | -h  display  this  help  message  Run  vps_configure.pl: 

# /hsphere/ shared/ scripts /vps-conf igure . pi 

Do  you  really  want  to  reconfigure  your  VPSs  [y/n]? 

Kernel : 2.4. 21-freevps-l . 2-lhugemem 
FreeVPS  patch  build:  1080548030 

Base  FreeVPS  tools  package:  freevps-tools-1 . 2-1 
Parallels  H-Sphere  VPS  scripts  package:  hsphere-vps-1 . 2-1 
RedHat  release:  RH73 

To  perform  basic  configuration  for  all  virtual  servers,  run  the  scipt  and  follow  the 
instructions  step  by  step  (on  page  359). 
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Create  VPS 


To  create  new  Virtual  Private  Server,  run  the  vps-post-config.pl  script: 

. /vps-post-conf ig.pl  VPS_HOST_NAME 

And  put  the  following  parameters  to  STDIN: 

i p=address  : mask  : hdev  - IP  to  be  assigned  to  this  VPS  and  allowed  on  network 
interface  HDEV  on  your  VPS  box; 

dlimit=xxxx  - Disk  limit  in  Mb; 

mlimit=xxxx  - Memory  Limit  in  Mb; 

plimit=xxxx  - Limit  on  the  number  of  running  processes; 

filelimit=xxxx  - Number  of  opened  files  limit; 

tcplimit=xxxx  - TCP  sockets  limit; 

rootpwd=*  * * * - User  root  password; 

ctrl+d  - Press  Ctrl+d  to  stop  data  input. 

Example: 

Create  a VPS  with  the  following  configuration: 

Hostname:  231. tst 

IP  address:  192.168.112.231,  mask:  255.255.255.0 
Disk  limit:  3000Mb 
Memory  limit:  512Mb 

Limit  on  the  number  of  running  processes:  1000 
Root  password:  1 

[root@vps  scripts]#  . /vps-post-conf ig . pi  231. tst 

IP=1 92. 168. 112. 231: 255. 255. 255.0 [press  Enter] 

DLIMIT=3000 [press  Enter] 

MLIMIT=512 [press  Enter] 

PLIMIT=1000 [press  Enter] 

ROOTPWD=l [press  Enter]  [press  Ctrl+d]  (end  of  data  input) 

vps-post-conf  ig . pi  creates  the  $HSVPSFILES/  231.tst/231.tst.in  file 
(Default:  /hsphe  re  /local/  conf  ig/vserver/  cp/231.tst/231.tst.in)  with  the 
input  parameters,  and  registers  VPS  in  the  list  of  known  vservers: 

$vpsconfigs/vps .list  (Default: 

/hsphere/ local/ conf ig/vserver /vps .list) 


Check  the  list  of  VPSs: 

[root@vps  scripts]#  cat  /hsphere/local/conf ig/vserver/vps . list 
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You  would  get  something  like  this: 

DELETE=" " 

VSERVERS="3 : 231 . tst" 

Format: 

delete="hostnamei  hostname2  hostname3  " - the  list  of  VPSs  scheduled  for 
deletion,  separated  with  whitespaces; 

VSERVERS="CONTEXT_IDl  : HOSTNAMEl  CONTEXT_ID2  : HOSTNAME2  " - the  list  of 

known  VPSs,  separated  with  whitespaces; 
context  id  is  a virtual  server  ID 

Migrate  VPS 

VPS  migration  is  performed  by  the  vps-migrate . pi  script  that  moves  VPS(s)  to 
another  host.  This  script  uses: 

■ OpenSSH  client: 

■ for  secure  copying  (scp  remote  file  copy  program) 

■ for  executing  commands  on  a remote  machine 

■ tar  archiving  utility. 

To  perform  a migration,  access  to  remote  servers  and  logging  into  them  automatically 
without  entering  the  password  each  time  is  required  from  the  "source"  box.  So,  the 
access  keys  should  be  copied  from  the  "source"  box  into  the  destination  box.  If  such 
keys  are  not  uploaded,  the  script  does  it  for  you  (use  the  — put-ssh-key  option). 

Preparation: 

1 Suspend  the  VPS  server  on  the  "source"  box. 

2 Configure  the  destination  machine  to  be  VPS  server  host: 

■ Install  all  required  packages  (FreeVPS  kernel,  FreeVPS  tools,  Parallels  Fl- 
Sphere  VPS  scripts). 

■ Complete  all  configuration  tasks. 

Actions  performed  by  the  script: 

■ The  remote  host  VPS  servers  configuration  is  loaded  and  checked 

■ Platform  compatibility  is  checked  for  the  VPS  box  and  the  destination  host.  For 
example,  a VPS  under  Enterprise  Linux  can't  be  moved  to  a host  under  RedFlat 
Linux  release  7.3. 

■ The  script  checks  whether  a VPS  with  the  same  name  as  the  migrated  one  exists 
on  the  destination  box 

■ Available  free  disk  space  on  the  destination  host  VPS  home  partition  is  checked  as 

Free  space  > VPS  disk  usage*1.5 

■ The  script  checks  if  the  VPS  server  virtual  context  number  exists  on  the  destination 
box: 
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■ if  the  migrated  VPS  server  virtual  context  does  not  exist  on  the  destination  box, 
the  VPS  is  created  with  this  context 

■ if  it  does  exist,  the  first  free  virtual  context  is  used  for  the  migrated  VPS 

■ Network  interface  which  all  the  virtual  network  interfaces  were  attached  to  is 
checked.  If  a network  interface  does  not  exist  on  the  destination  host,  new  one  is 
used,  and  the  VPS  network  is  reconfigured  to  be  used  to  assign  virtual  network 
interfaces. 

■ VPS  home  is  archived  using  the  tar  utility  filtered  through  gzip 

■ MD5SUM  for  the  source  file  is  compared  with  that  of  the  file  copied  to  the  remote 
host 

■ VPS  traffic  data  is  migrated  to  the  destination  box 

■ Post-migration: 

■ configuration  quota  check)  is  restored  within  3 minutes  by  the  crpn/vps- 
cron-fix.pl  cron 

■ Migrated  VPS  is  suspended  on  the  destination  box,  and  should  be  resumed  via 
Parallels  H-Sphere  or  manually. 

For  help,  run: 

# . /vps -migrate .pi  --help 

vps-migrate . pi  # Moves  VPS(s)  to  another  host. 

Usage : 

vps-migrate . pi  --host=<host>  [ --user=<name>]  --vps=v<ps  name>|--all  [-- 
put-ssh-key]  [--help] 

--host  # <host>  - host  (DNS  name/IP  address)  to  migrate  VPS(s) 

to . 

--user  # <name>  - username  to  be  used  to  log  into  the  host. 

# If  username  is  not  specified,  the  name  of  the  user 
executing  the  script  will  be  taken. 

--vps  # <vps  name>  - VPS  to  be  migrated. 

--all  # Migrate  all  known  VPSs. 

--put-ssh-key  # Generate  and  upload  public  SSH  keys  to  remote  box. 
--help  # Print  this  help  information. 


Delete  VPS 

vps-delete.pl 

SYNTAX: 

. /vps -delete . pi  VPS_HOST_NAME 

1 It  removes  existing  VPS  [vps_host_name],  all  its  configuration  files,  removes 
[vps_host_name]  from  the  list  of  known  VPS. 

2 If  [vps_host_name]  is  being  created  by  cron  at  the  moment,  [vps-delete.pl]  posts 
deletion  request  for  VPS  (sets  the  DELETE  parameter  in  the  vps  .list  file) 

3 All  deletion  requests  are  processed  by  vps-cron-deiete . pi  cron  every  4 
minutes. 
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VPS  Cron  Scripts 

These  are  VPS  scripts  scheduled  in  cron  on  the  host  server: 

*/5  * * * * /hsphere/shared/scripts/cron/vps-cron . pi  >/dev/null  2>&1 
59  */l  * * * /hsphere/shared/scripts/cron/vps-cron-traf . pi  >/dev/null 
2>&1 

*/4  * * * * /hsphere/shared/scripts/cron/vps-cron-delete . pi  >/dev/null 
2>&1 

*/3  * * * * /hsphere/shared/scripts/cron/vps-cron-f ix . pi  >/dev/null 
2>&1 

vps-cron.pl 

The  $vps scripts/ cron/ vps-cron .pi  script  ( Default : 

/hsphere/ shared/ scripts/ cron/ vps-cron  .pi)  runs  every  5 minutes.  It  is  used 
to  install  and  configure  new  Virtual  Private  Servers. 

The  script  works  as  follows: 

1 It  checks  the  list  of  known  vservers  and  takes  each  VPS  and  processes  requested 
tasks  from  the  $hsvpsfiles/vps_name/vps_name  . in  file  ( Default : 

. . . / cp/VPS_NAME/VPS_NAME  . in). 

2 If  the  requested  task  is  successfully  done,  it  creates  a note  in  the 

$hsvpsfiles/vps_name/vps_name  . out  file  ( Default : 

. . . / cp/VPS_NAME/VPS_NAME  . out) 

3 If  all  of  the  requested  tasks  are  done,  it  creates  the  DONE  file: 

$HSVPSFILES/VPS_NAME/VPS_NAME  . done  {Default: 

. . . / cp/vps_name/vps_name  . done),  and  deletes  the  request  file: 

$HSVPSFILES/VPS_NAME/VPS_NAME  . in  {Default: 

. . . / cp/VPS_NAME/VPS_NAME  . in). 

4 It  creates  the  FLAG  file:  $statcronpid  (Default: 

/var/iog/hsphere/vps  cron.pid)  with  its  own  PID,  to  prevent  executing 
another  copy  of  it. 

5 It  creates  all  configuration  files  required  for  VPSs: 

$vpsconfigs/vps_name  . conf  (Default: 

/hsphere /local/ conf ig/vserver /VPS  NAME .conf) 
$vpsconfigs/vps_name . sh  (Default: 

/hsphere /local/ conf ig/vserver /VPS  NAME . sh) 

6 It  installs  basic  Linux  RH7 . 3 packages  and  additional 
packages  if  configured,  creates  services,  set  limits,  assigns 
IPs,  and  finally,  starts  VPS. 

vps-cron-traf.pl 

Processes  VPS  network  traffic  statistics.  Creates  files  with  VPS  daily  traffic  statistics: 

/hsphere /local/var/ statistic/DD. MM. YYYY . vps . txt 
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vps-cron-delete.pl 

This  cron  script  that  runs  every  4 minutes  deletes  VPS  server(s)  scheduled  for 
removing. 

VPS  server  is  scheduled  for  removing  if  it  cannot  be  deleted  immediately  after  the 
removing  request  was  sent,  e.g.  when  other  tasks  need  to  be  finished  first. 

Names  of  the  VPS  servers(s)  scheduled  for  removing  are  listed  delimited  with 
whitespace  in  the  delete  parameter  of  the 

/hsphere/ local/  conf  ig/vserver/vps  .list  configuration  file. 

Example: 

# cat  /hsphere/local/config/vserver/vps . list 

DELETE="vpsl .psoft  vps2.psoft" 

VDU=" " 

VSERVERS="3 : 230 .psoft  4:vpsl. psoft  5:test.test  6:vps2. psoft 
7:vps4. psoft  8:vps5. psoft  9:vps6. psoft 
10 :vps3 .psoft  11 :vps7 .psoft  12 :vps9 .psoft 

13 rblabla . test . tst  14 rvpsll .psoft  15 :vpsl2 .psoft  16 :vpsl3 .psoft  17:vps- 
rh73 -blank. psoft 

18 : vpsl4 .psoft  21 : newacc . test . tst 

22 : j umbo . j umbo2  3 : vps2  00 . hs . test  24 : vps2  03 . hs . test  25 : vps2  07 . hs . test 
26 : vps212 . hs . test  27 :myvps . test 
2 8 : my- server .test  29: krambambuli .test" 

vps-cron-fix.pl 

This  script  fixes  some  VPS(s)  configuration:  limits,  usage,  etc. 

For  instance,  it  can  fix  VPS  server(s)  configuration  that  was  "lost"  when  you  upgraded 
the  FreeVPS  kernel  after  the  host  system  (physical  box)  reboot. 

Fixed  parameters: 

■ VPS  server  virtual  context  recreated 

■ VPS  root  directory  (new  root  for  the  created  virtual  context)  set 

■ VPS  server  files  context  fixed 

■ VPS  server  inside  user/group  quotas  for  all  filesystems  configured  in  /etc/fstab 
checked 

■ VPS  disk  usage  calculated 

■ all  limits  restored 

The  script  runs  as  a cron  job  and  is  configured  to  fix  corrupted  configuration  every  3 
minutes.  The  script  also  checks  and  fixes  VPS  servers(s)  daily. 

If  needed,  you  can  run  the  script  manually.  Use  — vps  to  fix  a particular  VPS  and  -f  | - 
-force  to  forcefully  fix  a virtual  server(s)  even  if  its(their)  configuration  is  uncorrupted. 


IMPORTANT:  It  is  recommended  that  you  stop/suspend  VPS  server(s)  before  the  fix. 


For  help,  run: 
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# vps-cron-f ix . pi  --help 

vps-cron-f ix . pi  # Script  for  checking  and  fixing  VPS(s)  configuration: 
limits,  usage,  etc. 

# The  script  is  configured  to  check  (and  to  fix  if 
needed)  VPS(s)  configuration  every  3 minutes  (run  as  a cron  job) . 

# VPS(s)  are  fixed  daily  anyway. 

Usage : 

vps-cron-f ix . pi  [ --vps=<name> | -v  <name>]  [--force | -f ] 

-v|--vps  # Fixes  particular  VPS. 

# If  not  set  - script  will  fix  all  known  VPS  servers, 

-f | --force  # Run  script  by  force  (even  if  it  was  run  today 

already) . 

--help  # Print  this  help  information. 


vps-cron-net-reconfig.pl  (VPS  Network  Reconfiguration  Cron) 

Location:  $VPSSCRIPTS/cron/vps-cron-net-reconfig.pl  (by  default 
/hsphere/ shared/ scripts /cron/ vps- cron-net -recon f ig . pi) 

This  script  runs  every  5 minutes  as  cron  to  reconfigure  virtual  servers'  network  (on  page 
336).  If  subnet  configuration  is  changed,  it  reconfigures  all  affected  virtual  servers' 
configuration.  If  subnet  default  gateway  or  mask  is  changed,  it  reconfigures  and  restarts 
network  for  each  virtual  server.  If  network  interface  is  changed  on  a virtual  server,  it 
restarts  this  virtual  server. 

Usage: 

vps-cron-net-reconfig.pl  [--vps=<name>]  [--force] 

--vps  # Process  particular  VPS. 

# If  not  set  - script  will  process  all  registered  virtual 

servers . 

--force  # Run  script  by  force  --help  # Print  this  help  information. 

Examples: 

vps-cron-net-reconfig.pl  --vps=vps . test  --force 

# Process  VPS  server  vps. test  forcefully,  even  if  the  reconfig  flag  is 
not  set 

vps -cron -net -recon fig . pi  --vps=vps .test 

# Process  VPS  server  vps. test  if  the  reconfig  flag  is  set 
vps-cron-net-reconfig.pl  --force 

# Process  all  registered  virtual  servers,  even  if  reconfigure  flag  is 
not  set 

vps -cron -net -recon fig . pi 

# Process  all  registered  VPS  server (s)  if  the  reconfig  flag  is  set 
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VPS  Configuration  Scripts 

./vps-addip.pl  VPS_HOST_NAME  IP:MASK 

Assigns  new  IP  address  to  the  vps_host_name  virtual  server. 

./vps-rmip.pl  VPS_HOST_NAME  IP[:MASK] 

Removes  IP  from  vps_host_name. 

./vps-dlimit-set  VPS_HOST_NAME  DISK_LIMIT_VALUE 

Sets  disk  usage  limit  for  vps_host_name  to  disk_limit_value,  in  Mb. 

./vps-dlimit-get  VPS_HOST_NAME 

Returns  disk  limit  and  disk  usage  for  vps_host_name. 

./vps-mlimit-set  VPS_HOST_NAME  MEMORY_LIMIT_VALUE 

Sets  memory  limit  for  the  vps_host_name  server  to  memory_limit_value,  in  Mb 

./vps-mlimit-get  VPS_HOST_NAME 

Returns  memory  limit  and  memory  usage  for  vps_host_name 

. /vps-plimit-set  VPS_HOST_NAME 
PROCE  S S_L  IMI  T_VALUE 

Sets  limit  on  the  number  of  processes  running  on  vps_host_name  to 
PROCESSLIMITVALUE,  in  Mb 

./vps-plimit-get  VPS_HOST_NAME 

Returns  the  limit  on  and  the  number  of  processes  running  on  vps_host_name 

./vps-flimit-get  VPS_HOST_NAME 

Returns  file  handlers  limit,  and  the  number  of  opened  at  this  moment  files 

VPS_HOST_NAME 

./vps-flimit-set  VPS_HOST_NAME 


Sets  file  handlers  limit  for  vps  host  name 
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./vps-tcplimit-get  VPS_HOST_NAME 

Returns  the  limit  on  socket  connections  and  the  number  of  established  connections  for 

VPS  VPS_HOST_NAME 

./vps-tcplimit-set  VPS_HOST_NAME 

Sets  limit  for  established  socket  connections  for  VPS  vps_host_name 

./vps-dev-speed.pl 

Tools  to  get|set  the  speed  of  virtual  network  interface. 


Note:  Virtual  network  interface  speed  must  be  divisible  by  64000. 


Usage: 

vps-eth-speed . pi  VPS_NAME  [ --dev=<device> | -d  <device>]  --get | --set 
<SPEED> 

For  more  information,  please  run:  vps-dev-speed.pl  — help 

./vps-dev-speed-set  VPS_NAME  [--dev=<device>|-d  <device>] 
<SPEED> 


Sets  work  speed  to  <speed>  Kb/sec  for  virtual  network  interface  <device>  on  Virtual 
Private  Server  vps  name 


Note:  Virtual  network  interface  speed  (<speed>  value)  must  be  divisible  by  64000. 

If  — dev=<device>  | -d  <device>  option  not  specified,  <speed>  value  will  be  set 
to  all  registered  virtual  network  interfaces  on  VPS  vps_name 


./vps-dev-speed-get  VPS_NAME  [--dev=<device>|-d  <device>] 

Returns  work  speed  for  virtual  network  interface  <device>  on  Virtual  Private  Server 

VPS_NAME 

Note:  If  — dev=<device>  | -d  <device>  option  not  specified,  returns  speed  for  all 
virtual  network  interfaces  registered  on  VPS  vps_name,  in  the  following  format: 

VDEV0  SPEED0 
VDEVl  SPEEDl 
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./vps-start.pl  [VPS_HOST_NAME  | [-a|«all]] 

Turns  on  vps_host_name,  or  all  known  stopped  VPS  servers  if  the  -a  | — all  option 
is  specified. 

./vps-stop.pl  [VPS_HOST_NAME  | [-a|-all]] 

Turns  off  vps_host_name,  or  all  known  running  VPS  servers  if  the  -a  | — all  option 
is  specified. 

./vps-suspend.pl  [VPS_HOST_NAME  | [-a|-all]] 

Suspends  (turns  off  and  sets  ONBOOT=no)  vserver  [vps_host_name],  or  all  known 
VPS  servers  if  the  -a  | — all  option  is  specified. 

./vps-resume.pl  [VPS_HOST_NAME  | [-a|--all]] 

Resumes  (turns  on  and  sets  ONBOOT=yes)  vserver  [vps_host_name],  or  all  known 
VPS  servers  if  the  -a  | — all  option  is  specified. 

./vps-rootpwd.pl  VPS_HOST_NAME 

To  set  new  password  for  user  root,  send  it  to  STDIN. 

./vps-du.pl 

Returns  disk  usage  for  all  known  VPSs  on  the  host  server  in  the  format  required  by 
Parallels  H-Sphere  Control  Panel. 

./vps-get-config.pl  VPS_HOST_NAME 

Returns  all  VPS  configuration  parameters  in  the  format  required  by  Parallels  H-Sphere 
Control  Panel. 
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View  List  of  Installed  VPS's 

The  . /vps-iist . pi  script  returns  brief  information  about  all  VPS  installed  on  the 
host  server,  installed  VPS  packages,  values  of  configuration  variables. 

Example: 

# . /vps-list.pl 

Kernel  release:  2 . 4 . 21-freevps-l . 3-22smp 
FreeVPS  kernel  patch  build:  0 [19691231] 

FreeVPS  tools  release:  1.3-9 

Parallels  H-Sphere  VPS  release:  1.3-6. 4 [20050426] 

Linux  release:  CentOS  release  3.3  (final)  [CentOS3] 

Free  disk  space  on  VPS  home  [/home/hsphere/local/vservers] : 9346  Mb 
Virtual  Private  Servers  found  on  the  host: 


ID  NAME  STATUS  VDEV: HDEV: IP/MASK+ | - (UP | DOWN)  DISK  (Mb)  MEMORY  (Mb)  SWAP 
PROCESSES  CPU  (%)  TRAFFIC 

(Mb) __ 

s--h--used (Mb) 

5 vpsl.psoft  run.  ethO : ethO : 10 . 0 . 0 . 2/24-  0 1707.6  0 0.8  0.5  05000 
0.0 

6 vps2 . psof t run.  ethO : ethO : 1 60 . 7 9 . 224 . 138 /24+  0 425.0  0 2.2  1.4  0 8 0 
0 0 0.0 

Display  all  settings  for  VPSs  on  this  host  [y/n]? 

Install/Uninstall  Additional  Packages 

To  install  an  additional  template  or  package  into  completely  created  virtual  server  use 

vps-pkg-inst . pi  script. 

Run#  . /vps-pkg-inst.  pi  — help  to  get  help  on  the  script  options: 

vps-pkg-inst . pi 

# Install  template  or  single  package  into  Virtual  Private 
Server ( s ) 

Usage : 

vps-pkg-inst . pi  --vps=<vps  name>|--all  -- 
package=<package  name> | --template=<template>  [--help] 

--vps  # Cvps  name>  - VPS  server  name  to  install 
package/template 

--all  # install  package/template  into  all  registered  and 
complately  created  VPS  servers 

--package  # <package  name>  - RPM  package  file  to  be  installed 
full  path  and  name 

--template  # <template>  - template  to  be  installed  name. 

# rpm  <template> . cf g templete  configuration  file 
must  be  located  in  corresponding  operating  system  VPS 
configuration  directory 

# All  RPM  packages  included  in  rpm_<template> . cf g 
file  must  be  located  in  corresponding  operating  system 
distributive  packages  directory 

--help  # Print  this  help  information. 

Example : 
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vps-pkg-inst . pi  --vps=vps . test  --template=web- server 

# Install  web-server  template  packages  into  VPS  server  named  vps.test 
vps-pkg-inst . pi  --all  --template=system-tools 

# Install  system-tools  template  packages  into  all  registered  on  the 
host  VPS  servers 

vps-pkg-inst . pi  --vps=vps . test  --package=/pub/RedHat/RHES3/vim- 
enhanced-6 .2.98-l.i386. rpm 

# Install  vim-enhanced-6 . 2 . 98-1  package  into  VPS  server  named  vps.test 

During  template  installation  the  script  tries  to  start  default  (corresponding  to  installing 
template/package)  services.  Any  other  service  should  be  started  manually  from  inside 
of  the  VPS.  No  services  configuration  is  performed  during  the  template/package 
installation.  Please  read  more  about  virtual  server  template  creation  and  management 
in  the  Parallels  H-Sphere  VPS  Templates  (on  page  348). 

To  unistall  any  template  or  package  installed  inside  virtual  server,  use  vps-pkg- 
remove.pl  script 

Run#  . /vps-pkg-remove.pi  — help  to  get  help  on  the  script  options: 

vps-pkg-remove . pi  # Uninstall  template  or  single  package  from  Virtual 
Private  Server (s) 

Usage : 

vps-pkg-remove . pi  --vps=<vps  name>|--all  --package=<package  name>|-~ 
template=<template>  [--help] 

--vps  # <vps_name>  - VPS  server  name  to  uninstall  package/template 
--all  # uninstall  package/template  from  all  registered  and  completely 
created  VPS  servers 

--package  # <package  name>  - RPM  package  to  be  uninstalled  name 
--template  # <template>  - template  to  be  uninstalled  name. 

# rpm_< tempi ate> . cfg  template  configuration  file  must  be 
located  in  corresponding  operating  system  VPS  configuration  directory 
--help  # Print  this  help  information. 

Example : 

vps-pkg-remove . pi  --vps=vps . test  --template=web-server 

# Uninstall  web-server  template  packages  from  VPS  server  named 
vps . test 

vps-pkg-remove.pl  --all  --template=system-tools 

# Uninstall  system-tools  template  packages  from  all  registered  on  the 
host  VPS  servers 

vps-pkg-remove .pi  --vps=vps . test  --package=vim-enhanced-6 .2.98-1 

# Uninstall  vim-enhanced-6 . 2 . 98-1  package  from  VPS  server  named 
vps . test 

Be  carefull  when  packages  are  removed.  We  do  not  provide  any  back-ups  to  enable 
services  (corresponding  to  a template/package  removal)  configuration  restore.  If  any  of 
the  packages  (single  or  included  into  the  removed  template)  required  by  any  other 
template  installed  , the  package  will  be  not  removed. 
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Check  VPS  Files  for  Changes 

This  action  is  performed  by  the  vps-fiies-md5-check.pl  script.  It  compares  info  of 
the  package  installed  files  with  that  of  the  package  metadata  stored  in  the  rpm 
database.  Parameters  compared  are  size,  MD5  sum,  permissions,  type,  owner,  and 
group  of  each  file. 

The  --verify  option  of  the  RPM  Package  Manager  is  used.  For  reference,  please 
turn  to  the  rpm  manual. 

Example  of  usage:  Say,  the  file  info  has  been  changed  as  a result  of  the  box  hacking. 
The  script  checks  the  file  inside  VPS  for  changes  and  proposes  to  copy  this  file  from 
the  host  system. 


WARNING:  We  strongly  recommend  not  to  overwrite  non-binary  files,  e.g.  configs.  This 
may  cause  the  system  malfunction. 

Before  copying,  find  out  which  files  have  been  changed  by  running  the  script  with  the 
listing  options. 


For  help  info,  run: 

# vps-files-md5-check.pl  --help 

vps-files-md5-check.pl  # Check  installed  files  information  for  changes. 
Usage : 

vps-files-md5-check.pl  --vps=<vps  name> | --root=<directory>  [--list|-- 
list-all  [--detailed] ] [--copy-all] 

--vps  # <vps_name>  - VPS  name  to  check. 

--root  # <directory>  - new  root  directory  to  check  (packages  must  be 
installed  with  the  --root  option) . 

--list  # List  changed  files. 

--list-all  # List  all  changed  files  (config,  license,  readme,  doc, 
ghost  file,  etc.) . 

--detailed  # Show  file  changes. 

--copy-all  # Do  not  ask  to  copy  modified  file  from  the  host. 

--help  #Print  this  help  information. 

Example: 

# . /vps-f iles-md5-check . pi  --vps=vps4 . psof t --list-all  --detailed 

S.5....T  c /etc/pam. d/system-auth 
%config  configuration  file, 
file  Size  differs 
MD5  sum  differs 
mTime  differs 

T c /etc/inittab 

%config  configuration  file. 
mTime  differs 

T c /etc/mail/sendmail . cf 

%config  configuration  file. 
mTime  differs 

T c /etc/krb5 . conf 

%config  configuration  file. 
mTime  differs 

S.5....T  c /etc/sysconf ig/rhn/up2date-uuid 
%config  configuration  file, 
file  Size  differs 
MD5  sum  differs 
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mTime  differs 

In  the  above  example,  there  are  no  files  to  overwrite  because  all  of  them  are  %conf  ig 
configuration  files. 

In  the  next  example  we  are  changing  /bin/true  binary: 

# . /vps-f iles-md5-check . pi  --vps=vps4 . psof t --list-all  --detailed 
< . . . > 

. . 5 . . . . T /bin/true 
MD5  sum  differs 
mTime  differs 

< . . . > 

The  script  shows  that  MD5  sum  for  rpm  database  differs  from  that  of  the  binary  file.  To 
copy  the  file  from  the  host,  run: 

# . /vps-f iles-md5-check . pi  --vps=vps4 . psof t 

Would  you  like  to  copy  /bin/true  from  the  host  [y/n]?  y 

VPS  IP  Migration  Tool 

vps-ip-migrate.pl  is  used  to  change  virtual  servers'  IP  addresses  (in  other  words, 
IP  migration). 

For  help,  run: 

# . /vps-ip-migrate .pi  --help 

vps-ip-migrate . pi  # VPS  server  IP  migration  script. 

Usage : 

vps-ip-migrate . pi  --vps=<vps_name> | --all  --xml=<xml_ip  map>  [--help] 
--vps  # <vps  name>  - VPS  server  name  to  perform  IP  migration 
--all  # perform  IP  migration  for  all  registered  VPS  servers 
--xml  # <xml  ip  map>  - XML  structured  IP  map  migration  file 
--help  # Print  this  help  information. 

Example: 

vps-ip-migrate . pi  --vps=vps . test  - -xml=ip_map . xml 

# Perform  IP  migration  for  vps. test  according  to  the  ip  map . xml  IP  map 
file 

vps-ip-migrate . pi  --all  --xml=ip  map . xml 

# Perform  IP  migration  for  all  registered  in  the  host  VPS  servers 
according  to  the  ip  map . xml  IP  map 

file 

Options: 

■ — all  - when  it's  used,  IPs  will  be  changed  for  all  Virtual  Servers  registered  in  the 
host  (physical  machine) 

■ — vps  =<vps_name>  - used  for  IP  change/migration  on  a single  <vps_name>  VPS 

■ — xmi=<xmljp_map>  - full  name  of  structured  IP  migration  map  xml  file  (on  page 

43) 

When  calling  the  script,  it's  mandatory  to  use  -all  or  -vps  option. 


IMPORTANT!  This  script  does  not  make  any  changes  to  Parallels  Fl-Sphere  cluster.  It 
physicaly  changes  IP(s)  created  ONLY  inside  VPS  server(s). 

Read  on  IP  migration  (changing  IPs)  for  the  Parallels  Fl-Sphere  cluster  (on  page  40). 
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VPS  Network  Configuration  Tools 

Parallels  H-Sphere  VPS  1 .4-1  provides  adding  multiple  subnets  and  network  gateways 
(on  page  342)  to  virtual  servers.  The  following  scripts  located  in  the  $vpsscripts/ 
(/hsphere/ shared/ scripts/  by  default)  are  responsible  for  managing  VPS 
subnets: 

■ vps -subnets -add . pi  - add  new  subnet  to  network  gateways  (subnets 
configuration  file); 

■ vps -subnets -change . pi  - change  existing  subnet  configuration; 

■ vps-subnets-dei  .pi  - remove  configuration  for  particular  subnet; 

■ vps-subnets-iist . pi  - print  subnet  configuration; 

■ vps -subnets -xml -get . pi  - print  XML  structured  subnet  configuration; 

■ vps-subnets-xml-put . pi  - save  XML  structured  subnet 
configuration; 

Run  these  scripts  with  the  — help  option  for  detailed  usage  info. 

These  scripts  work  with  the  subnet  configuration  XML  file  (on  page  343). 

vps-subnets-add.pl 

Configures  subnet  (IP  addresses  to  be  assigned  to  newly  created  VPS  servers)  with 
gateway,  IP  mask  and  network  interface.  Please  turn  to  your  data  center  system 
administrators  for  subnet  configuration  information. 

Usage: 

vps-subnets-add.pl  --addr=<addr>  --device=<device>  --gateway=<gateway> 

- -mask=<mask>  [--help] 

--addr  # <addr>  - subnet  address  --device  # <device>  - Linux  style  name 
of  the  network  interface  to  which  subnet  IPs  will  be  assigned. 

# For  example  ethO  (ethl,  ...) 

# To  list  available  interfaces  run:  net-if ace-list . pi 
--gateway  # <gateway>  - gateway  to  be  used  by  IPs  from  this  subnet 
--mask  # <mask>  - IPs  mask 

--help  # Print  this  help  information. 

Example: 

vps-subnets-add.pl  --addr  192.168.112.0  --device  ethl  --gateway 
192.168.112.1  --mask  255.255.255.0 

Configures  all  192.168.1 12.x  IPs  (subnet  192.168.1 12.0)  to  be  assigned  to  network 
interface  ethl  with  gateway  192.168.1 12.1  and  mask  255.255.255.0 
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vps-subnets-change.pl 

Changes  subnet  configuration,  such  as,  gateway  or/and  IP  mask  and/or  network 
interface. 

Usage: 

vps-subnets-change.pl  --addr=<addr>  -~device=<device> | -- 
gateway=<gateway> | - -mask=<mask>  [--help] 

--addr  # <addr>  - subnet  network  address  whose  configuration  is  to 
be  changed 

--device  # <device>  - Linux  style  name  of  the  new  network  interface  to 
which  subnet  IPs  will  be  assigned. 

# For  example  ethO  (ethl,  ...) 

--gateway  # <gateway>  - new  gateway  to  be  used  by  IPs  from  this  subnet 
--mask  # <mask>  - new  IP  mask  --help  # Print  this  help  information. 

Example: 

vps-subnets-change.pl  --addr  192.168.112.0  --device  eth2 

Configures  all  192.168.1 12.x  IPs  (subnet  192.168.1 12.0)  to  be  assigned  to  new 
network  interface  eth2  (use  old  gateway  and  mask) 

vps-subnets-del.pl 

Deletes  subnet  configuration  according  to  the  XML  config  file  (on  page  343). 

Usage: 

vps-subnets-del.pl  <addr>  [--help] 

# <addr>  - subnet  address  whose  configuration  is  to  be 

removed 

--help  # Print  this  help  information. 

Example: 

vps-subnets-del.pl  192.168.112.0 

Removes  192.168.1 12.0  subnet  configuration. 

vps-subnets-list.pl 

Prints  VPS  subnet  configuration  from  the  XML  config  file  (on  page  343). 

Usage: 

vps-subnets-list.pl  [--help|-h] 

--help  # Print  this  help  information. 

vps-subnets-xml-put.pl 

Stores  virtual  servers'  subnet  configuration  into  the  XML  config  file  (on  page  343). 
Usage: 

vps-subnets-xml-put.pl  [--helpl -h] 

--help  # Print  this  help  information. 
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Device  Management 

Global  and  per  virtal  context  device  management  is  available  in  command-line  mode 
Starting  with  kernel-f  reevps-1 . 5-6  and  f reevps-tools-1 . 4-3. 

Low  level  management  is  provided  with  vaccess  tool  that  comes  in  FreeVPS  tools 
package.  To  get  more  info  on  the  vaccess  tool,  run: 

# man  vaccess 

Virtual  device  management  isn't  yet  available  in  Parallels  H-Sphere  control  panel 
interface. 


Global  VPS  Device  Management 

Global  VPS  device  management  is  realized  through  two  scripts:  vps-dev-giobai- 
add.pl  and  vps-dev-global-del . pi. 

By  default  only  these  character  devices  required  for  basic  virtual  servers  functionality 
are  enabled: 

1.3,  1.5,  1.7,  1.8,  1.9,  5.0,  5.2,  136. all,  200. all  (null,  zero,  full,  random,  urandom,  tty, 
ptmx,  tun) 

Block  devices  are  not  enabled  by  default  and  if  needed,  must  be  enabled  additionally. 


To  check  what  devices  are  enabled  on  your  host  virtual  servers,  run  the  following 
command: 

■ character  devices: 

# vserver_ctl  --ctx  1 --exec  cat  /proc/vservers/access/chardev 

■ block  devices: 

# vserver_ctl  --ctx  1 --exec  cat 
/proc/vservers/access/blockdev 


vps-dev-global-add.pl 

Enables  device  for  all  virtual  servers  and  has  the  following  syntax: 

# ./vps-dev-global-add.pl  --help 

vps-dev-global-add.pl  # Enables  device  globally  (for  all  virtual 
servers ) 

Usage : 

vps-dev-global-add.pl  - - dev=<dev_narae> | (--ftype=<file_type>  -- 
dtype=<device_type>)  [--help] 

--dev  # <dev_name>  - device  name 
--ftype  # <file_type>  - device  file  type: 

# c - a character  special  file 

# b - a block  special  file 

--dtype  # <device  type>  - device  type  in  the  MAJOR. MINOR  format 

# for  example:  1.3 

--help  # Print  this  help  information. 
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Example : 

vps -dev- global -add . pi  --dev=" tun" 

# Enable  /dev/tun  for  all  virtual  servers 
vps-dev-global-add . pi  --ftype=c  --dtype="10 . 200" 

# Enable  character  device  type  10.200  (/dev/tun)  for  all  virtual 
servers 


vps-dev-global-del.pl 

Disables  device  globally  for  all  registered  virtual  servers  and  its  syntax  is  the  same  as 
for  script  vps-dev-global-add. pi 

To  get  more  info  on  the  script,  run: 

# ./vps-dev-global-del.pl  --help 

Per  Virtual  Server  Device  Management 

Per  virtual  server  device  management  is  realized  through  two  scripts:  vps-dev- 
add.pl  and  vps-dev-del  .pi. 

You  can  check  devices  enabled  for  individual  virtual  context  by  the  following  command: 
■ character  devices: 


# vserver  ctl  --ctx  1 
Char 

--exec  cat  /proc/vservers/<ID>  | 

grep 

block  devices: 

# vserver  ctl  --ctx  1 
Block 

--exec  cat  /proc/vservers/<ID>  | 

grep 

where,  <ID>  is  a virtual  context  ID,  for  example  3,  4,  etc. 

Parallels  H-Sphere  VPS  device  management  tools  enable  usage  of  virtual  servers 
names  instead  of  virtual  contexts  IDs. 


vps-dev-add.pl 

Enables  individual  device  for  all  virtual  servers  and  has  the  following  syntax: 

vps -dev- add . pi  - - vps=<vps_name>- -dev=<dev_name> | ( - - f type=< f i 1 e_type> - - 
dtype=<device_type>)  [--help] 

where  — vps  # <vps_name>  is  a virtual  server  name  and  other  parameters  are  the 
same  as  for  vps-dev-global-add. pi. 

For  example: 

vps-dev-add.pl  --vps=vps  . tst  --dev="tun"  will  enable  /dev/tun  for  virtual 
server  vps . tst; 
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vps-dev-add . pi  -~vps=vps  . tst  -~ftype=c  --dtype="10 . 200"  will  enable 
character  device  type  10.200  (/dev/tun)  for  virtual  server  vps.tst 

To  get  more  info  on  the  script,  run: 

# . /vps-dev-add . pi  --help 

vps-dev-del.pl 

Disables  device  for  virtual  server  and  its  syntax  is  the  same  as  for  script  vps-dev-add. pi 
To  get  more  info  on  the  script,  run: 

# ./vps-dev-del.pl  --help 

For  example: 

vps-dev-del  .pi  --vps=vps  . tst  --dev="tun"  will  disable  / dev/ tun  for  virtual 
server  vps  . tst;  vps-dev-del  .pi  — ftype=c  — dtype="10 .200"  will  disable 
character  device  of  the  10.200  type  (which  is  /dev/tun)  for  virtual  server  vps . tst. 

To  get  more  info  on  the  script,  run: 

# ./vps-dev-del.pl  --help 
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Backing  Up  VPS  Content 

The  document  describes  the  structure  of  files  and  directories  to  back  up  on  Parallels  hl- 
Sphere  VPS  server. 

Parallels  H-Sphere  backup  script  (on  page  432)  is  not  provided  for  backing  up  Parallels 
H-Sphere  VPS  server,  which  is  a standalone  server  installed  separately  from  Parallels 
H-Sphere.  You  need  to  back  up  Parallels  H-Sphere  VPS  content  manually  or  write  your 
own  backup  script. 

Back  up  the  following  files  and  directories  on  the  VPS  host  server: 

1 The  VPS  host  configuration  file.  It  is  common  to  all  virtual  servers: 

/hsphere/ local/ conf ig/vserver/vps . cfg 

2 The  file  with  the  list  of  virtual  servers.  To  find  out  its  pathname,  run  under  root: 
cat  /hsphere/local/conf ig/vserver/vps . cfg  | grep  VPSLIST 

By  default,  it  is: 

VPSLIST=/hsphere/local/ conf ig/vserver/vps . list 

3 FreeVPS  configuration  files  (*.config)  for  each  virtual  server.  They  are  located 
in  the  vpsconfigs  directory: 

# cat  /hsphere/local/conf ig/vserver/vps . cfg  | grep  VPSCONFIGS 
By  default,  the  vpsconfigs  directory  is: 

VPSCONFIGS=/hsphere/local/ config/vserver 

So,  by  default,  FreeVPS  configuration  files  will  be 

/hsphere /local/ config/vserver/* . conf ig 

1 Parallels  H-Sphere  VPS  configuration  files  (Parallels  H-Sphere 
related  configuration).  They  are  located  in  the  hsvpsfiles  directory: 

# cat  /hsphere/local/conf ig/vserver/vps . cfg | grep  HSVPSFILES 
By  default,  the  hsvpsfiles  directory  is: 

HSVPSFILES=/hsphere/local/ config/vserver/ cp 

Note:  We  recommend  backing  up  Parallels  H-Sphere  VPS  configuration  files 
separately  for  each  virtual  server. 

2 Virtual  servers'  content.  Virtual  servers  are  located  in  the 
VPSHOME  directory: 

# cat  /hsphere/local/conf ig/vserver/vps . cfg | grep  VPSHOME 
By  default,  the  vpshome  directory  is: 

VPSHOME=/hsphere/ local/vservers 

Note:  We  recommend  backing  up  each  virtual  server  content  separately. 


342 


Virtual  Private  Servers 


3  VPS  templates  (on  page  348)  for  each  supported  operating 

system.  They  are  located  in  the  vpsconfigs/os_type  directories, 
where  OS_TYPE  is: 

■ RH73  for  Red  Hat  7.3; 

■ RHAS3  for  Red  Hat  AS  3; 

■ RHES3  for  Red  Hat  ES  3; 

- RHWS3  for  Red  Hat  WS  3; 

■ WBEL3  for  White  Box  EL  3; 

■ CentOS3  for  CentOS  3.x 


Adding  VPS  Network  Gateways 

Parallels  H-Sphere  provides  adding  multiple  subnets  and  network  gateways  to  virtual 
servers  via  administrator  control  panel. 

> To  configure  network  gateways: 

1 Select  E.Manager  ->  VPS  Network  Gateways. 

2 Click  the  Add  button  to  Add  new  Network  Gateway. 

3 In  the  VPS  Boxes  section  Click  Show  Assigned  Devices  for  the  server  you 
want  to  edit. 

4 On  the  page  that  appears,  click  Assign  Device  for  the  subnet  you  are 
adding. 

5 Select  the  network  device  to  associate  the  subnet  with. 

6 Click  Submit  Query. 

In  this  section: 


VPS  Subnet  XML  Configuration 
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VPS  Subnet  XML  Configuration 

Parallels  H-Sphere  provides  adding  multiple  subnets  and  network  gateways  (on  page 
342)  to  virtual  servers.  The  respective  VPS  network  scripts  (on  page  336)  configure 
VPS  subnet  addresses,  gateways,  masks  and  physical  network  interfaces  by  means  of 
the  special  XML  file  /hsphere/local/ conf  ig/vserver/ subnets  . xml  which 
looks  like: 

<?xml  version= ' 1 . 0 ' standalone= ' yes ' ?> 

<subnets> 

<subnet  addr="192 . 168 . 112 . 0" 
device="ethl " 
gateway="192 .168.112.1" 
mask="255. 255. 255.0"  /> 

<subnet  addr="192 . 168 . 114 . 0" 
device="ethO " 
gateway="192 .168.114.1" 
mask="255. 255. 255.0"  /> 

<subnet  addr="192 . 168 . 116 . 0" 
device="ethl " 
gateway="192 .168.116.1" 
mask="255. 255. 255.0"  /> 

</subnets> 
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Parallels  H-Sphere  VPS  Configuration 
Parameters 


The  default  VPS  configuration  file  is  /hsphere/local/ conf  ig/vserver/vps  . cfg. 

Below  is  a sample  config  file.  To  change  these  parameters  interactively,  run  the 
configuration  script  and  follow  the  instructions  step  by  step,  (on  page  359) 


WARNING:  1 . Do  not  change  location  of  the  configuration  file! 

2.  It  is  strongly  recommended  not  to  make  changes  to  the  configuration  file  manually! 


# (c)  2004  Positive  Software  Corporation 

# 

# Distributed  only  with  Parallels  H-Sphere 

# 

# 

# 

# http://www.psoft.net 

# 

####################################################################### 

################## 

####################################################################### 

################## 

# Default  configuration  file  for 

# 

# creation  and  management  of  Virtual  Private  Servers. 

# 

# It  is  strongly  recommended  that  you  do  not  make  any  changes  to  this 
file  manually.  # 

# Run  [#  /hsphere/shared/scripts/vps-conf igure .pi] 

# 

# and  perform  step-by-step  configuration  for  your  virtual 

servers . # 

####################################################################### 

################## 

# System  parameters 

# Linux  release 
LINUXCODE=undef 

# FreeVPS  kernel  patch  BUILD 
BUILD=0000000001 

# Virtual  Servers  network  configuration 

# Set  the  ONBOOT  option  to  'no'  to  disable  virtual  servers  at  boot  time 
ONBOOT=yes 

# Boot-time  protocol 
BOOTPROTO=static 

# You  can  set  various  capabilities.  By  default,  the  vservers  are  run 

# with  a limited  set.  In  some  cases 

# you  can  to  give  a little  more  capabilities  (such  as  CAP  NET  RAW, 
CAP_NET_ADMIN) 

S_CAPS="CAP_NET_RAW  CAP_NET_ADMIN  CAP_SYS_RESOURCE " 

# Default  gateway  for  virtual  servers 
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GATEWAY=0 .0.0.0 

# Name  server (s)  IP  addresses: 

NAMESERVER=" " 

# Ethernet  network  device  use  to  setup  IP(s)  to  be  assigned  to  the  VPS. 

# This  is  generally  ethO . 

# IP (s)  will  be  configured  when  you  start  the  VPS  and  un-configure  when 
you  stop  it. 

I PROOTDEV=ethO 

# Set  VDEVALIASE  to  'yes'  to  enable  virtual  ethernet  devices  aliases. 

# Using  virtual  ethernet  devices  aliases  allow  you  configure  up  to  16 
different  device  aliases 

# (with  IP  address  assigned) 

# per  each  virtual  ethernet  device  (maximum  16  different  virtual 
ethernet  devices  can  be  created  in  VPS) . 

# So,  using  aliasing,  you  can  assign  up  to  16x16  IP  address  to  one  VPS. 
VDEVALIAS=no 

# Max  number  of  virtual  ethernet  devices  per  virtual  context 
MAXVDE V S = 1 5 

# Max  number  of  virtual  ethernet  device  aliases  per  each  virtual 
ethernet  device  at  current  virtual  context 

# Required  when  device  aliasing  used  (option  VDEVALIAS=yes ) only. 

MAXVDE VAL IAS  E S = 1 5 

# Virtual  device  on  which  IP  alias  will  work. 

# Not  urgent  in  this  version  of  VPS. 

VIPROOTDEV=ethO 

# Vinterface  controlling  flags 
VDE VFLAGS = "local" 

# Virtual  Servers  creating  options 

# Below  is  the  list  of  default  services  initialized  at  virtual  servers' 
boot  time 

START  SERVICES="anacron  atd  crond  kdcrotate  network  random  rawdevices 
sshd  syslog  xinetd  vpsinit  netfs 

portmap  gpm  identd  ipchains  iptables  nscd  sendmail  ypbind" 

# Set  ADDITIONAL  to  'yes'  if  you  want  to  install  ADDITIONAL_PACKAGES 

# and  ADDITIONAL_SERVICES  to  be  set  up  to  start  at  virtual  servers' 
boot  time 

ADDITIONAL=no 

# Additional  packages  available  for  installation  on  VPS 

ADD I T I ONAL_PACKAGE S_AVAI LABLE= " gcc  samba  http  sendmail  php  mysql 
postgresql  me  up2date" 

# Additional  packages  to  be  installed  for  VPS 
ADD I T I ONAL_PACKAGE  S = " " 

# Additional  services  available  for  setup 

ADDITIONAL  SERVICES  AVAILABLE="httpd  sendmail  mysqld  postgresql  rhnsd 
winbind" 

# Additional  services  to  be  set  up 
ADDITIONAL_SERVICES=" " 

# Set  CHECKRPM  to  'yes'  if  you  want  all  packages  required  to  build  VPS 
be  checked. 

CHECKRPM=no 

# VPS  log  options 

# Path  to  the  log  file  for  VPS  control  scripts 
LOGFILE=/var/log/hsphere/vps . log 

# Log  file  max  size  in  Mb  LOGFILESIZE=l 

# Number  of  log  files  stored. 

LOGFILENUM=7 

# Log  detailization . Available  detailizations : INFO  CRON  WARN  ERROR 
FATAL  TEST 

# List  of  available  types  enclosed  in  brackets. 

LOGDETAILS=" INFO  CRON  WARN  ERROR  FATAL  TEST  syst  open" 
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# VPS  related  files 
#Virtual  Private  Server  HSphere  scripts  package  version  file 

HSVPS_VERSION_FILE=/hsphere/ local /conf ig/vserver /HSVPS_VERS ION 

# Path  to  the  file  which  consists  the  list  of  known  VPSs, 

# and  list  of  VPSs  scheduled  for  deletion. 

VPSLIST=/hsphere/ local/ conf ig/vserver/vps .list 

# File  where  PID  of  running  VPSs-creating  script  (vps-cran . pi ) is 
stored 

CRONPID=/var/log/hsphere/vps  cron .pid 

# File  where  PID  of  running  VPSs-traffic  script  (vps-cran-traf . pi ) is 
stored 

STATCRONPID=/var/log/hsphere/stat  vps  cron. pid 

# VPS  working  directories 

# Virtual  Private  Server  libraries 
USR_LIB_VSERVER=/ usr / lib/vserver 

# Path  to  the  files  with  RPM  lists  (rpm  base.cfg)  required  for  basic 
Linux  RedHat  installation 

RPMBASE=/hsphere/ local/ conf ig/vserver 

# Path  to  Linux  RedHat  packages  (RPMS) 

LINUXRPMS=/home /RedHat/ 7 . 3/RedHat/RPMS 

# Path  to  VPS  config  files 
VPSCONFIGS=/hsphere/local/ conf ig/vserver 

# ROOT  directory  for  all  VPS  servers. 

VPSHOME=/hsphere/local/vservers 

# Path  to  Parallels  H-Sphere  Control  Panel  configuration  files  for  VPS 
HSVPSFILES=/hsphere/local/ conf ig/vserver/ cp 

# Path  where  all  Parallels  H-Sphere  VPS  scripts  are  located 
VPSSCRIPTS=/hsphere/ shared/ scripts 

# Path  where  VPS  statistics  is  stored  (e.g.,  VPS  traffic) 
STATISTICFILES=/hsphere/local/var/ statistic 

# Path  to  VPS  statistics  files  loaded  to  Control  Panel 
STATISTICLOADED=/hsphere/local/var/ statistic/ loaded 

# Path  to  packages  required  by  Parallels  H-Sphere 
HSINSTALLPKG=/hsphere/ install /pkg 

# Public  key  file  to  verify  RPM  packages  built  and  signed  by  Red  Hat, 
Inc . 

RPM_GPG_KEY=/ usr/ share/ doc/ redhat-release-7 . 3/RPM-GPG-KEY 

# Additional  PATHs 

# Binary  directory  SBIN=/sbin 

# Users ' binary  directory 
USRJ3BIN=/usr/sbin 

# Vserver  related  programs 

# Main  'vserver'  script 
VSERVER_CMD=/usr/ sbin/vserver 

# 'vserver  ctl ' program 
VSERVER_CTL=/ usr/ sbin/vserver_ctl 

# 'vserver  limit'  program 

VSERVER  LIMIT=/usr/ sbin/vserver_limit 

# ' chcontext ' program 
CHCONTEXT_CMD=/ usr/ sbin/ chcontext 

# ' chroot ' program 
CHROOT=/ usr/ sbin/ chroot 

# ' vdu ' program  VDU=/usr/sbin/vdu 

# 'setattrib'  program 
SETATTRIB=/ usr/ sbin/ setattrib 

# 'vifconfig'  program 
VIFCONFIG=/usr/ sbin/vifconf ig 

# 'if config'  program 
IFCONFIG=/ sbin/ ifconf ig 

# 'chkconfig'  program 
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CHKCONFIG=/ sbin/ chkconf ig 

# Additional  programs  and  paths 
#cat-  concatenate  files  and  print  on  the  standard  output  program 
CAT=/bin/cat 

#grep  - print  lines  matching  a pattern  program  GREP=/bin/grep 
#awk  - pattern  scanning  and  processing  language 
AWK=/bin/ awk 

#head  - output  the  first  part  of  files 
HEAD=/ us r /bin /head 

# Print  system  information  program 
UNAME=/bin/uname 

# usermod  - Modify  a user  account 
USERMOD=/ usr/ sbin/ usermod 

# ps  - report  process  status 
PS=/bin/ps 

# rpm  - RPM  Package  Manager 
RPM=/bin/ rpm 

# df  - report  filesystem  disk  space  usage 
DF=/bin/ df 

# mknod  - make  block  or  character  special  files 
MKNOD=/bin/mknod 

# touch  - change  file  timestamps 
TOUCH= /bin /touch 

# mount  - mount  a file  system 
MOUNT= /bin /mount 

# umount  - unmount  file  systems 
UMOUNT=/bin/ umount 

# crontab  - maintain  crontab  files  for  individual  users  (V3) 
CRONTAB=/usr/bin/ crontab 

# In  - make  links  between  files 
LN=/bin/ln 

# quotacheck  - scan  a filesystem  for  disk  usage,  create,  check  and 
repair  quota  files 

QUOTACHECK=/ sbin/ quotacheck 

# utility  for  download  files  from  the  Web 
WGET=/ usr/bin/wget 

# list  directory  contents  utility 
LS=/bin/ls 

# sed  - a Stream  Editor  SED=/bin/sed 

# route  - show  / manipulate  the  IP  routing  table 
ROUTE=/ sbin/ route 

# Path  where  gzip  is  placed 
GZIPPATH=/bin/ gzip 

# sleep  - delay  for  a specified  amount  of  time 
SLEEP=/bin/ sleep 

# gpg  - encryption  and  signing  tool 
GPG=/usr/bin/gpg 

# Some  URLs 

# URL  to  Linux  RPMs 

LINUXRPMSITE=http : / /f tp . redhat . com/ pub/ redhat/linux/7 . 3/en/os/ i38  6/RedH 
at/RPMS 

# VPS  processes  files 

# VPS  system  calls  file 
SETUP=/proc/vservers/ setup 

# Per  context  running  configuration 
SELF=/proc/vservers/ self 

# Required  packages 

# HSphere  VPS  scripts  package 
HSVPSPACKAGE=hsphere-vps 

# FreeVPS  tools  package 
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FREEVPS TOOLS PACKAGE=freevps- too Is 
# Linux  virtual  server  utilities  package 
VSERVERPACKAGE=vserver- 


VPS  Templates 

VPS  template  is  a predefined  set  of  RPMs  to  install  a certain  service,  tool  or 
application. 

Templates  are  installed  to  VPS  upon  its  creation  or  to  a live  VPS.  Basically,  template  is 
a structured  file  with  the  list  of  RPM  packages,  including  their  names,  full  version  and 
platform  architecture. 

All  VPS  templates  are  located  in  the  $vpsconfigs/$linuxcode  directory.  Default 
location: 

Red  Hat  Linux  release  7.3'.  /hsphere/local/config/vserver/RH73 

Red  Hat  EL  3,  CentOS  3.x,  White  Box  EL  3: 

/hsphere/ local/ conf ig/vserver/RHES3 

VPS  templates  have  the  following  filename  format: 
rprn_<template__name> . cfg 

where  <template_name>  may  contain  any  characters  possible  in  Unix  file  names,  except 
and 

RPM  files  listed  in  the  templates  must  be  located  either  in  your  $LINUXRPMS  directory 
(this  location  can  be  configured  by  running  the  vps-configure  .pi  script),  or  in  the 
Parallels  H-Sphere  packages  directory  $hsinstallpkg/$linuxcode: 

Red  Hat  Linux  7.3\  /hsphere/install/pkg/RH73 

Red  Hat  EL  3,  CentOS  3.x,  White  Box  EL  3:  /hsphere/instaii/pkg/RHES3 


In  this  section: 
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Creating  and  Modifying  VPS  Templates 

RPM  files  listed  in  template  file  must  satisfy  all  dependences  during  their  installation. 

To  configure,  modify,  create  new  templates,  run  the  vps-conf igure.pl  script.  You 
will  see  the  following  prompt: 

Application  Templates  available  to  install: 

1 - [ ] dns-server 

2 - [ ] development-tools 

3 - [ ] ftp-server 

4 - [ ] mail-server 

5 - [ ] mysql-server 

6 - [ ] news-server 

7 - [ ] perl-full 

8 - [ ] pgsql-server 

9 - [ ] samba-server 

10  - [ ] system-tools 

11  - [ ] web-server 


[ a ] - add  template 
[ d ] - delete  template 

[ c ] - change  template  installation  order 

(must  satisfy  package  dependences  during  installation) 

[ n ] - new  template 
[ m ] - modify  template 
[ s ] - save  and  exit 
[ e ] - exit  without  saving 

Enter  the  number  of  a template  to  be  turned  on/off,  or  choose  any  of  the  options: 

■ [ a ]- add  template  - select  this  option  to  add  an  existing  template  to  be 
available  for  VPS  installation. 

■ [ d ] - delete  template  - select  this  option  to  delete  an  existing  template  from 
the  list  of  available  templates  for  VPS  installation. 

■ [ n ] - new  template  - select  this  option  to  create  your  own  custom  template. 
Here  you  will  be  promted  for  the  template  name  and  the  names  of  RPM  packages 
to  be  included  into  the  template.  Package  names  listed  in  the  template  must  be 
each  in  new  line.  When  you  finish,  press  Ctrl+D. 

■ [ m ] - modify  template  - use  this  option  to  modify  the  list  of  packages 
included  to  the  template. 

Then,  you  save  the  list  and  exit  ( [ s ] ),  or  exit  without  save  ( [ e ] ). 
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Default  Templates 

base 

■ Core  VPS  Linux  installation.  It  includes: 

■ vps  kernel; 

■ networking  support; 

■ OpenSSH  connection; 

■ basic  tools  and  libraries; 

■ service  configuration  tools; 

■ cron,  scheduling  tasks  support; 

■ utility  to  control  the  network  packet  filtering  code  in  Linux  kernel; 

■ system  logging  management  tools; 

■ man  pages  (documentation)  from  Linux  Documentation  Project  (LDP); 

■ Perl  high-level  programming  language; 

■ Aspell  spelling  checker; 

■ Python  programming  language; 

■ Sendmail  - widely  used  Mail  Transport  Agent  (MTA). 

samba-server 

Windows  file  server.  This  package  group  allows  you  to  share  files  between  Linux  and 
MS  Windows&tm;  systems. 

It  includes: 

■ samba  protocol  for  sharing  files,  printers,  and  other  information  (such  as  available 
files  and  printers); 

■ CUPS  (Common  UNIX  Printing  System):  portable  printing  layer  for  UNIX  operating 
systems. 

ftp-server 

These  tools  allow  you  to  run  FTP  server  on  VPS's. 

They  include: 

■ fast,  read-only,  anonymous  FTP  server; 

FTP  server  daemon. 

pgsql-server 

PostgreSQL  database  server.  This  package  group  includes  packages  useful  for  use 
with  PostgreSQL. 


It  includes: 
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■ advanced  Object-Relational  database  management  system  (DBMS)  - PostgreSQL 
server; 

an  implementation  of  DBI  for  PostgreSQL  for  Perl; 

a dynamic  shared  object  (DSO)  that  can  be  compiled  in  to  the  Apache  Web  server 
to  add  PostgreSQL  database  support  to  PHP. 

web-server 

These  tools  allow  you  to  run  a Web  server  on  VPS: 

■ powerful,  full-featured,  efficient,  and  freely-available  Apache  Web  server; 

■ PHP  - an  HTML-embedded  scripting  language; 

■ a utility  to  convert  Active  Server  Page  (ASP)  files  run  on  the  Microsoft  IIS  Web 
server,  to  PHP  pages; 

■ additional  modules  to  give  Apache  Web  server  the  ability  to  understand  the  DAV 
(Distributed  Authoring  and  Versioning)  protocol  of  HTTP  extensions,  to  incorporate 
a Perl  interpreter  into  the  Apache  Web  server,  to  provide  strong  cryptography  for 
the  Apache  Web  server  via  Secure  Sockets  Layer  (SSL)  and  Transport  Layer 
Security  (TLS)  protocols; 

■ Web  server  log  analysis  program  - Webalizer; 

dns-server 

This  package  group  allows  you  to  run  DNS  name  server  (BIND)  on  the  system. 

It  includes: 

■ BIND  (Berkeley  Internet  Name  Domain)  - an  implementation  of  the  DNS  (Domain 
Name  System)  protocols.  BIND  includes  a DNS  server  (named)  which  resolves  host 
names  to  IP  addresses;  a resolver  library  (routines  for  applications  to  use  when 
interfacing  with  DNS);  and  tools  for  verifying  that  the  DNS  server  is  operating 
properly; 

■ configuration  files  that  will  make  BIND,  the  DNS  name  server,  act  as  a simple 
caching  nameserver. 

mysql-server 

MySQL  database  server.  This  package  group  contains  packages  to  be  used  with 

MySQL. 

It  includes: 

■ a multi-user,  multi-threaded  SQL  database  server; 

■ a MySQL  interface  for  Perl; 

■ a dynamic  shared  object  that  will  add  MySQL  database  support  to  PHP. 

mail-server 

These  packages  allow  you  to  configure  an  IMAP  or  Postfix  mail  server. 

They  include: 
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■ server  daemons  for  both  the  IMAP  (Internet  Message  Access  Protocol)  and  POP 
(Post  Office  Protocol)  mail  access  protocols; 

■ Mail  Transport  Agent  (MTA),  supporting  LDAP,  SMTP  AUTH  (SASL)  - Postfix. 

news-server 

This  group  allows  you  to  configure  the  system  as  a news  server. 

It  includes: 

■ an  automatic  spam  filter  for  Usenet  news  servers  and  routers  - Cleanfeed; 

■ the  inews  program; 

■ INN  (InterNetNews)  is  a complete  system  for  serving  Usenet  news  and/or  private 
newsfeeds. 

perl-full 

Additional  modules  for  Perl  programming  languages. 

It  includes: 

■ Expat  C library  for  parsing  XML; 

■ database  access  Application  Programming  Interface; 

■ module  for  the  handling  of  tar  archives; 

■ library  which  allows  you  to  handle  bit  vectors,  sets  (of  integers); 

■ module  providing  an  interface  for  testing  and  setting  process  limits  and  priorities; 

■ module  provides  support  for  the  https  protocol  under  LWP; 

■ date/time  manipulation  modules; 

■ various  XML  partner  modules  for  Perl; 

■ module  for  perl  to  parse  and  extract  information  from  HTML  documents. 

system-tools 

This  group  is  a collection  of  various  tools  for  the  system,  such  as  the  client  for 
connecting  to  SMB  shares  and  tools  to  monitor  network  traffic. 

It  includes: 

■ arbitrary  precision  numeric  processing  arithmetic  language  and  an  interactive 
arbitrary  precision  stack  based  calculator; 

■ LiSt  Open  Files  tool  to  list  information  about  files  that  are  open  and  running  on  a 
Linux/UNIX  system; 

■ utility  to  decode  and  encode  multilingual  streams  using  many  coding  systems; 

■ Pax  - the  POSIX  standard  archive  tool; 

■ Pinfo  - an  info  file  (or  man  page)  viewer  with  a user  interface  similar  to  the  Lynx 
Web  browser  interface; 

■ procinfo  command  to  get  system  data  from  the  /proc  directory; 

■ stat  utility; 
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■ superuser  do  (sudo); 

■ symlinks  utility; 

■ tree  utility; 

development-tools 

These  tools  include  core  development  tools  such  as  automake,  gcc,  python,  and 
debuggers. 

They  include: 

■ Autoconf  - tool  for  configuring  source  code  and  Makefiles; 

■ public  domain  LALR  parser  generator; 

■ CVS  (Concurrent  Version  System)  is  a version  control  system; 

■ Berkeley  DB  version  1 ,2,3  (4); 

■ utility  that  allows  you  to  show  dialog  boxes  in  TTY  (text  mode)  interfaces; 

■ diff  and  diffstat  - compares/reads  the  output  of  files; 

■ various  DocBook  documentations; 

■ Scanners  programs  which  can  recognize  lexical  patterns  in  text; 

■ the  cc  and  gcc  GNU  compilers  for  compiling  C code; 

■ C++ support  to  the  GNU  C compiler; 

■ gd  graphics  library. 


VPS  Limits 


Parallels  H-Sphere  enables  to  configure  VPS  resource  limits  in  Parallels  H-Sphere  VPS 
plans  and  in  user  control  panel. 


Memory 


MLIMIT 


Disk  Limit  is 
the  maximum 
disk  usage  for 
a VPS  server. 
Default  - 
disabled  (set 
to  0). 


Memory  Limit 
is  the 

maximum  total 
memory 
usage  for 
processes 
running  and 
libraries 
loaded  on  a 
VPS  server. 
Default  - 
disabled  (set 
to  0). 


Requirements  & 
Restrictions 


Disk  Limit  cannot 
be  exceeded.  No 
more  data  will  be 
dumped  into  the 
disk  if  disk  usage 
reaches  Disk 
Limit. 

Minimal  VPS 
installation 
requires  ~ 

500MB  allocated 
disk  space. 


Memory  Limit 
depends  on  tasks 
running  on  a VPS 
server. 

Memory  Limit 
cannot  be 
exceeded.  No 
more  memory  will 
be  allocated  if 
VPS  total 
memory  usage 
reaches  Memory 
Limit. 

VPS  server  total 
memory  usage  = 
resident/virtual 
memory  usage  + 
system  SWAP- 
Minimal  VPS 
installation 
requires  ~15- 
20Mb  allocated 
memory. 
Processes  are 
processed  by 
linux  OOM  - out 
of  memory  killer. 


Related  VPS  Scripts 


vps-dlimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  Mb  for  vps 
<vps_name> 

vps-dlimit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


vps-mlimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  Mb  for  vps 
<vps_name> 

vps-mlimit-get  - returns 
current  value  for  vps 
<vps_name> 
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Process 


PLIMIT 


Context 

RSS 


RSSLIM 

IT 


Process  Limit 
is  the 
maximum 
number  of 
processes 
running  inside 
a VPS  server. 
Default  - 
disabled  (set 
to  0). 


Context  RSS 
Limit  is 
maximum 
resident/virtual 
memory 
usage  for 
processes 
running  and 
libraries 
loaded  on  a 
VPS  server. 
Default  - 
disabled  (set 
to  0). 


FILELIM 

IT 


File  Limit  is 
the  maximum 
number  of  file 
handlers 
opened  inside 
a VPS  server. 
Default  - 
disabled  (set 
to  0). 


Process  Limit 
cannot  be 
exceeded.  No 
new  processes 
will  be  created  if 
the  number  of 
running 
processes 
reaches  Process 
Limit.  All  new 
processes  will  be 
killed. 

Minimal  VPS 
installation 
requires  -10-20 
processes  to  run. 


Context  RSS 
Limit  depends  on 
virtual  memory 
available  on  the 
host  server 
(physical 
machine),  on 
tasks  running  on 
a VPS,  and  on 
total  memory 
limit. 

Context  RSS 
Limit  cannot 
exceed  Memory 
Limits  When  VPS 
virtual  memory 
usage  exceeds 
RSS  limit,  VPS 
starts  to  use  the 
host  server's 
SWAP. 

Recommended 
value  for  Context 
RSS  Limit  = 1/3  * 
Memory  Limit. 


File  Limit  cannot 
be  exceeded.  No 
new  files  will  be 
opened  if  the 
number  of 
opened  file 
handlers  reaches 
File  Limit. 

Minimal  VPS 
installation 
requires  -150- 
200  opened  file 
handlers  allowed. 


vps-proclimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  value  for  vps 
<vps_name> 

vps-proclimit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


vps -rss limit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  Mb  for  vps 
<vps_name> 

vps -rss limit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


vps -f limit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  value  for  vps 
<vps_name> 

vps -f limit -get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 
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TCP 

Socket 


TCPLIM 

IT 


TCP  Socket 
Limit  is  the 
maximum 
number  of 
TPC 

connections 
established  on 
a VPS  server. 
Default  - 
disabled  (set 
to  0). 


HARDC  CPU  Hard 


CPU 

Guarantee 
d (CPU 
Soft  Limit) 


SOFTC 

PU 


Limit  is  the 
maximum 
CPU  usage  (of 
all  host  server 
CPUs)  fora 
VPS  server. 
Default  - 
disabled  (set 
to  0). 


The  guaranted 
value  of  CPU 
resources  (in 
%)  which  can 
be  allocated 
by  virtual 
server  if  they 
are  required 
and  available 
in  host 
system. 
Default  - 
disabled  (set 
to  0). 


TCP  Socket  Limit 
cannot  be 
exceeded.  No 
new  connection 
via  TCP  (for 
example,  SSH 
connections)  will 
be  established  if 
their  number 
reaches  TCP 
Sockets  Limit. 


CPU  Hard  Limit 
must  be  less  than 
100%. 

CPU  Hard  Limit 
cannot  be 
exceeded.  When 
usage  reaches 
CPU  Hard  Limit, 
new  task  will  be 
waiting  for  free 
CPU  resources. 
That  increases 
system  load. 

CPU  Hard  Limit 
depends  on  VPS 
task  priority. 


CPU  Guaranteed 
Limit  must  be 
less  than  CPU 
Hard  Limit  and 
100%.  For  all 
registered  vps  on 
host  Summary 
CPU  Guaranteed 
Limit  values  must 
be  less  than 
100%. 


vps-tcplimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  value  for  vps 
<vps_name> 

vps-tcplimit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


vps-hcpulimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  value  for  vps 
<vps_name> 

vps-hcpulimit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


vps-scpulimit-set 

<vps_name>  <limit>  - sets  the 
limit  to  <limit>  value  for  vps 
<vps_name> 

vps-scpulimit-get 

<vps_name>  - returns  current 
value  for  vps  <vps_name> 


Note:  VPS  limit  labels  are  set  by  the  vps-get-config.pl  script.  See  VPS  Scripts 
(on  page  321). 


Hints  On  Handling  VPS  Limits 

■ Limit  values  depend  on  the  number  of  VPS's  running  on  the  host,  and  tasks  running 
on  them. 

■ When  summary  virtual  memory  size  used  by  VPS/context  exceeds  Memory  Limit 
value,  processes  can't  allocate  the  required  memory  and  fail  to  run. 

■ If  Memory  Limit  you  set  to  VPS  equals  the  whole  virtual  memory  available  on  the 
host,  in  a while  virtual  server  will  use  up  all  the  host's  swap. 

■ If  you  turn  off  both  Memory  and  Context  RSS  limits,  kernel  can  DoS  or  panic. 
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■ While  setting  initial  Disk  Limit  before  VPS  creation,  please  mind  that  it  must  be 
greater  than  minimal  Linux  RedHat  installation  size  (~450-500Mb).  Otherwise,  Disk 
Limit  will  be  turned  off  during  the  installation. 

■ For  lowlevel  virtual  server  limits  management  use  vserver_iimit  tool  provided 
by  FreeVPS.  For  more  info  about  it  run: 

# man  vserver  limit 


Changing  VPS  Solution 

In  Parallels  H-Sphere  you  can  install  VPS  server  based  on  FreeVPS  or  OpenVZ 
solution.  If  you  already  have  a VPS  logical  server  based  on  one  of  the  solutions, 
starting  with  Parallels  Pi-Sphere  VPS  2.0  it  is  possible  to  switch  to  another  solution  in 
console  or  from  Parallels  Pi-Sphere  Control  Panel 

Changing  Solution  from  Parallels  H-Sphere  Control 
Panel 

Parallels  Pi-Sphere  users  can  easily  switch  from  FreeVPS  to  OpenVZ  (and  vice  versa) 
solution  from  their  Control  panel.  For  this: 

1 Switch  from  one  solution  to  another  in  VPS  server  additional  options. 

2 Run  Parallels  H-Sphere  updater  from  CP. 

In  this  section: 


Changing  Solution  from  Console 

Changing  Solution  from  Parallels  H-Sphere  Control  Panel 
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Changing  Solution  from  Console 

To  change  VPS  solution  from  FreeVPS  to  OpenVZ  and  vice  versa,  use  the . /vps- 
change . pi  script.  The  script  takes  new  solution  name  for  a particular  virtual  server  or 
for  all  registered  on  the  host  virtual  servers. 

For  help,  run: 

# hsphere-scripts/vps-change .pi  -? 

Usage : 

vps-change . pi  --vps=VPS_NAME | --all  --soluion=SOLUTION  [--help | | 
man] 

Options : 

— vps=*VPS_NAME* 

Virtual  Private  Server  Name 
--all 

Change  solution  for  all  registered  in  the  host  virtual  servers 
— solution=* SOLUTION* 

New  virtual  private  server  solution.  Following  are  available:  *openvz* 
*freevps* 

--help | --? 

Print  the  usage  message 
--man 

Print  the  entire  manual  page 

The  VPS  will  work  under  new  solution  after  the  box  is  booted  with 
corresponding  kernel. 

VPS  is  suspended  while  solution  is  changed.  It  is  required  to  resume 
it . 

The  following  tasks  are  performed  during  the  solution  change: 

1 Virtual  server  config  structure  is  changed  to  become  compatible  with 
and  acceptable  by  new  solution 

2 VPS  virtual  network  is  completely  reconfigured.  Old  virtual  interfaces 
are  removed,  and  the  new  ones  are  created  with  the  same  IP  address 
configuration.  The  old/unused  virtual  network  configuration  is 
completely  removed. 

3 Virtual  context  flags  are  changed  to  be  compatible  with  new  solution. 

4 Internal  virtual  server  services  (daemon)  scripts  will  be  changed. 

5 Virtual  server  pre/post  start/stop  scripts  are  changed. 

WARNING: 


■ VPS  is  suspended  during  the  solution  change. 

■ VPS  will  work  under  new  solution  only  after  the  box  is  booted  with  a corresponding 
solution  kernel,  e.g.  if  you  change  VPS  solution  from  FreeVPS  into  OpenVZ,  you 
must  boot  the  box  with  OpenVZ  kernel. 

■ Please  pay  attention  to  virtual  servers  which  solution  was  not  changed:  they  will  not 
work  until  the  box  boots  the  kernel  of  other  solutions!  These  virtual  servers  will  be 
considered  as  corrupted. 
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Changing  Solution  from  Parallels  H-Sphere  Control 
Panel 

Parallels  H-Sphere  users  can  easily  switch  from  FreeVPS  to  OpenVZ  (and  vice  versa) 
solution  from  their  Control  panel.  For  this: 

1 Switch  from  one  solution  to  another  in  VPS  server  additional  options. 
Refer  to  Logical  Servers  section  of  Parallels  H-Sphere  Service 
Administrator  Guide. 

2 Run  Parallels  H-Sphere  updater  from  CP. 


Configuring  VPS  Host 

This  document  is  a step-by-step  instruction  on  how  to  globally  configure  all  virtual 
private  servers  from  the  VPS  host  server. 

Though,  Parallels  H-Sphere  VPS  interface  configuration  may  slightly  vary  from  version 
to  version,  the  core  procedure  remains  the  same: 

1 Log  into  the  VPS  host  server  under  root  and  run  the  VPS 
configuration  script: 

# /hsphere/ shared/ scripts/vps-configure .pi 

You'll  see  the  versions  of  VPS  packages  installed  on  your  host  server.  For  example: 

Kernel : 2.4. 2 1-f reevps-1 . 4hugemem 
FreeVPS  patch  build:  1114360337 

Base  freevps  tools  package:  f reevps-tools-1 . 3-17 
Parallels  H-Sphere  VPS  scripts  package:  hsphere-vps-1 . 3-6 . 7 
RedHat  release:  RH73 

With  the  further  steps,  you'll  perform  basic  configuration  for  all  your  virtual  servers. 
The  default  values  are  enclosed  in  square  brackets  ([  ]).  To  accept  them,  press 
ENTER. 

2 Point  to  all  Virtual  Private  Servers  home  directory  which  you  has 
created  during  installation: 

Please  point  to  the  directory  where  all  Virtual  Private 
Servers  will  be  stored. 

Make  sure  it  has  enough  free  space! 

The  default  is:  [/hsphere/local/vservers] 

After  entering  path,  you  will  be  informed  about  free  disk 
space  in  it: 

Free  disk  space  on  /hsphere/local/vservers:  XXXXXXXX  Mb 

3 Choose  the  gateway.  The  gateway  of  the  main  server,  suggested  as 
the  default,  should  be  selected  if  the  main  server  and  the  virtual 
private  servers  will  belong  to  the  same  subnet.  Otherwise,  enter  a 
different  gateway's  IP: 

Gateway  will  be  used  for  routing  by  VPSs:  [192.168.112.1] 
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4 Specify  the  IPs  of  your  name  servers.  If  you  are  running  the  script  for 
the  first  time,  no  defaults  are  suggested.  Once  you  enter  name  server 
IPs,  they  will  be  remembered  and  used  when  you  run  the  script  again: 

Enter  name  server  IP(s)  separated  with  spaces:  [192.168.112.1 
192.168 .112 .102] 

5 On  this  step,  the  script  tries  to  find  this  host's  network  device.  To 
accept  the  suggested  value,  press  Enter.  Otherwise,  enter  a different 
device  name: 

Host  ethernet  device  will  be  used  for  VPSs:  [ethO] 

6 If  you  need  to  assign  more  than  16  IPs  to  VPS,  type  "yes"  to  use 
ethernet  aliases: 

Would  you  like  to  use  virtual  ethernet  device  [ethO]  aliases 
instead  of  creating  new  virtual  devices  [yes/no]? 

Normally,  VPS  supports  up  to  1 6 virtual  ethernet  devices,  and  up  to  16  IPs  per  each 
virtual  ethernet  device,  thus  totally  16x16=256  IPs  available  for  assignment  per 
VPS.  But  if  it  requires  to  assign  more  than  16  different  IPs  to  VPS,  you  need  to 
reconfigure  your  VPS  to  assign  IPs  to  virtual  ethernet  devices  aliases. 

7 Specify  the  directory  with  the  full  set  of  RPMS.  If  you  don't  have  the 
RPMS,  they  will  be  downloaded  to  this  directory  on  the  next  step.  If 
your  RPMS  are  located  in  the  default  directory  (for  example,  in 

/home/RedHat/7 . 3 /RedHat /RPMS),  just  press  Enter,  otherwise, 
type  the  actual  path  to  the  RPMS  directory: 

Please  specify  where  Linux  RedHat  7.3  installation  RPMs  are 
located . 

The  default  is:  [ /home/RedHat/7 . 3/RedHat/RPMS] 

8 Then  you  will  be  asked  for  required  packages  checking. 

Configuration  script  can  perform  package  test  in  case  it  is  damaged, 
using  gpg  - encryption  and  signing  tool. 

To  say  "yes"  just  press  'Enter'  or  type  'y',  'yes'. 

Would  you  like  to  check  Linux  RH73  installation  RPMs  [y/n] ? 

9 You  can  install  on  your  virtual  servers  additional  sets  of  packages,  or 
VPS  templates  (on  page  348).  Default  VPS  templates  are: 

samba-server  - Windows  File  Server 

ftp-server  - FTP  Server 

pgsql-server  - Postgresql  SQL  Database 

web-server  - Web  Server 

dns-server  - DNS  Name  Server 

mysql-server  - MySQL  Database 

mail-server  - Mail  Server 

news-server  - News  Server 

perl-full  - Perl  programing  language  modules 

system-tools  - System  Tools 
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development-tools  - Development  Tools 

You  can  also  enable  some  additional  services: 

smb  - provide  SMB  network  services 

winbind  - Starts  and  stops  the  Samba  winbind  daemon 

postgresql  - This  is  the  init  script  for  starting  up  the  PostgreSQL  server 

aeplOOO  - load  and  unload  AEP1000/AEP2000  coprocessor  driver 

bcm5820  - BCM5820  - Broadcom  BCM5820  Cryptonet  init  script 

squid  - Squid  - Internet  Object  Cache 

tux  - This  starts  and  stops  the  TUX  kernel-based  http  server. 

httpd  - Startup  script  for  the  Apache  Web  Server 

named  - DNS  service 

mysqld  - This  service  takes  care  of  starting  and  stopping  the  MySQL  subsystem 
(mysqld) 

You  will  get  the  following  prompt: 

Would  you  like  to  install  additional  templates  such  as: 
"(templates  list  goes  here)"  [y/n]? 

If  you  choose  to  install  additional  packages,  you  will  have  the  opportunity  to 
configure  templates  and  services  to  be  available  on  your  Virtual  Private  Servers. 
Read  more  about  Parallels  H-Sphere  VPS  templates  (on  page  348). 


Additional  services : 

1 - [ 

] httpd 

2 - [ 

] sendmail 

3 - [ 

] mysqld 

4 - [ 

] postgresql 

5 - [ 

] rhnsd 

6 - [ 

+]  winbind 

[ a ] 

- add 

[ d ] 

- delete 

[ s ] 

- save  and  exit 

[ e ] 

- exit  without  saving 

Enter 

the  number  of  the  service  to  be  turned  on/off,  or  choose 

an  option: 

If  you  are  going  to  enable  new  Additional  services,  the  script  will  prompt  you  to 
enter  the  name  of  a service. 

Mind  that  service  must  be  installed  to  a virtual  server. 

/etc/rc . d/init . d/<service_name>  is  required  to  start/stop  the  service  in  your 
virtual  server(s). 

For  example,  to  enable  the  winbind  service,  packages  from  the  samba  list 

(/hsphere/local/ config/vserver/RH73/ rpm  samba  . cfg)  will  install  the 
/etc/rc. d/init. d/winbind  file. 

[ d ] - deletes  lists/services  from  the  additional  package  lists/services  enabled. 


362 


Virtual  Private  Servers 


[ c ] - changes  list  installation  priority. 

For  example,  installation  packages  from  the  http  package  list  (packages  required  to 
install  Apache  Web  server)  require  the  gcc  package  to  be  installed  first. 

[ n ] - helps  you  to  create  your  own  list  of  additional  packages  to  install. 

Enter  the  name  of  the  new  list  of  package  (i.e.,  my  list)  and  the  names  of  RPM 
packages  to  be  added  to  the  list.  Press  Enter  after  each  package  name.  When  you 
finish,  press  Ctrl+D. 

Remember  that  all  of  this  packages  must  be  located  in  the  RPMS  directory.  If  these 
packages  are  not  there,  you  will  be  prompted  to  download  them. 

Then,  you  save  the  list  and  exit  ([  s ]),  or  exit  without  save  ([  e ]). 

10  If  you  don't  have  required  RPM  packages  for  the  base  Linux 
installation  (e.g.  you  installed  RedHat  from  a CD-ROM),  answer  YES 
(type  ’yes'),  and  the  script  will  download  these  packages: 

Would  you  like  the  script  to  automatically  download  required 
for  Linux  RH73  installation  RPMs  [yes/no] ? 

11  If  you  choose  to  download  the  packages  (answered  YES  on  the 
previous  step),  you  will  be  prompted  for  their  location: 

Please  specify  the  URL  where  Linux  RH73  installation  RPMs  are 
located . 

The  default  is: 

[ftp://192.168.112. 77 /pub /RedHat/ 7 . 3 /RedHat /RPMS ] 

If  the  URL  is  valid,  the  download  will  start: 


Downloading  packages  . . . 
base  packages: 

4Suite-0 . 11 . 1-8 . i386 . rpm  [OK] 
Distutils-1. 0.2-2. noarch. rpm  [OK] 


202  packages  successfully  downloaded. 

0 packages  skipped. 

0 packages  failed  to  download. 

If  some  packages  fail  to  download,  please  download  them  manually  or  run  this 
script  once  again. 

12  Script  will  check  all  required  packages.  If  the  gpg  Linux  RPMs  public 
key  is  not  installed,  script  will  install  it. 

Also  script  will  import  Linux  RPMs  public  key  to  rpm  database. 

If  public  key  is  installed  and  imported,  you  will  see  it,  and  all  templates 
will  be  checked.  For  example: 


Linux  RH73  RPMs  public  key: 
/ root/ . gnupg/ pubring . gpg 


pub  1024D/DB42A60E  1999-09-23  Red  Hat,  Inc 
sub  2 04 8g/ 961 630A2  1999-09-23 

Checking  packages  required  for  VPS  initialization  . . . 
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Checking  in  'base'  template  ... 

13  Specify  if  all  VPSs  will  start  at  system  reboot.  Type  'y\  'yes'  or  press 
Enter  for  YES.  If  you  choose  'no',  none  of  your  VPSs  will  be  started 
automatically,  and  you  will  have  to  resume  every  individual  VPS 
manually  in  the  control  panel  after  the  system  reboot: 

Would  you  like  all  VPSs  to  start  at  physical  server  startup 
[y/n]? 

14  At  this  point,  the  script  will  finish  the  configuration  with  the  following 
notification  (see  VPS  cron  scripts  (on  page  326)  in  VPS  scripts 
documentation): 


Writing 

to  crontab: 

vps-cron-f ix . pi  [OK] 

Writing 

to  crontab: 

vps-cron.pl  [OK] 

Writing 

to  crontab: 

vps-cron-traf . pi  [OK] 

Writing 

to  crontab: 

vps-cron-delete . pi  [OK] 

Changing  chkconfig. 

. . [OK] 

At  the  end,  you’ll  be  prompted  to  save  the  changes  you  have  made: 

Save  your  changes  [y/n]? 

For  more  options  run: 

# /hsphere/shared/scripts/vps-configure .pi  --help 

VPS  confgiruration  parameters  (on  page  344)  set  by  the  vps-conf  igure  .pi  script 
are  Stored  in  the  /hsphere/ local/ conf  ig/vserver/vps  . cfg  file.  Do  not 

change  this  file  manually! 


Customizing  Operating  System 
Distributive  URLs 


You  can  customize  OS  distributive  URLs  in  a separate  VPS  config  file  located  in  the 

$VPSCONFIGS/$VPS_DISTR_URLS 

( /hsphere /local/ config/ vserver/ vps  . distr . url  by  default). 

File  format  example: 

CentOS 3= "ftp :// ftp . arcticnetwork . ca/pub/centos/3/os/i38  6/RedHat/RPMS 
f tp : / /f tp . arcticnetwork . ca/pub/ centos/ 3 /updates /i38  6" 

RH7  3="f tp : //f r2 . rpmf ind . net/linux/ redhat/7 . 3/en/os/ i3 8 6/RedHat/RPMS 
f tp : / /f r2 . rpmf ind . net/linux/ redhat/ updates/ 7 ,3/en/os/i386" 

WBEL3="f tp : //f tp . esat . net/mirrors/whiteboxlinux . org/3 . 0 / en/ os/i386/RedH 
at/RPMS 

ftp://ftp.esat. net/mirrors/whiteboxlinux . org/3 . 0/en/ updates/ " 
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This  chapter  tells  you  how  to  configure  MRTG  service  for  dedicated  servers. 

In  this  chapter: 

Configuring  MRTG 364 


Configuring  MRTG 

In  Parallels  H-Sphere  the  MRTG  software  (http://mrtq.hdl.com/mrtq.html)  is  used  for  the 
dedicated  hosting  feature.  This  software  is  installed  to  Parallels  H-Sphere  as  a logical 
server  from  hsphere-mrtg-rrd-x-x  package,  where  x-x  is  the  latest  available 
version. 

Mrtg  service  is  managed  by  supervise,  similarly  to  clamd,  spamd,  ftpd,  and  bind. 
Apache  service  with  configured  VirtualHost  for  mrtg  service  is  required  which  is 
provided  by  Apache  configuration. 

Mrtg  works  with  RRDtool  (http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/)  which 
improves  its  performance  and  graphing  flexibility.  RRDtool  is  used  as  the  logger  to 
MRTG.  It  stores  data  samples  on  each  of  the  network  switch  interfaces  (ports)  in  a 
separate  RRD.  To  minimize  size  of  the  database  files,  RRD  uses  the  consolidation 
mechanism.  It  guarantees  that  the  database  does  not  grow  over  time  and  that  old  data 
is  automatically  eliminated.  However  this  leads  to  degradation  of  accuracy.  For  the 
sake  of  high  degree  of  data  accuracy,  space  for  10080  samples  (35  days)  is  allocated. 
The  DSBandwidthLoader  daily  cron  acquires  data  from  RRDs  and  stores  it  into  the 
hsphere  database. 

Managing  MRTG  Service 

For  Linux: 

/etc/init.d/mrtg  stop  | start  | restart  | stat 

For  FreeBSD: 

/usr/local/etc/rc . d/mrtg . sh  stop  | start  | restart  | stat 
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Configuration  Directory  and  File 

Mrtg  configuration  directory  is  /hsphere/iocai/conf  ig/mrtg. 

/hsphere/iocal/ conf  ig/mrtg/mrtg . conf  - mrtg  configuration  file.  It  has  an 
include  for  /hsphere/iocal/ conf  ig/mrtg/ports/ index  . conf  which  in  its 
turn  contains  includes  for  files  corresponding  to  each  opeational  switch  port.  Such 
files  are  generated  dynamically  via  CP  interface  when  switch  ports  are  assigned  to 
dedicated  servers. 

Scripts  Processing  Data 

/hsphere/iocal/  conf  ig/mrtg/ scripts/  get  statistics  - gathers  data  from 
each  port  file. 

/hsphere/iocal/  conf  ig/mrtg/ scripts/  setstartbill  - sets  the  Start  billing 
period  date. 

/hsphere/iocal/ conf  ig/mrtg/ scripts/ f ormgraph  - draws  traffic  graphs. 


RRD  Files 


Mrtg  writes  RRD  files  to  /hsphere/iocal/ conf  ig/mrtg/ rrd  directory.  In  its 
subdirectories  image  files  with  bandwidth  representations  for  chosen  periods  are 
located: 

■ ~httpd/htdocs/rrd/d  - day 

■ ~httpd/htdocs/rrd/w  - week 

■ ~httpd/htdocs/rrd/m  - month 

■ ~httpd/htdocs/rrd/y - year 


The  Problem  with  Calculating  Large  (>100mbps) 
Bandwidth  Traffic 

It  is  a known  issue  that  MRTG  with  32-bit  counters  doesn't  calculate  correctly  the  traffic 
when  bandwidth  exceeds  100  Mbps.  A solution  is  to  switch  to  64-bit  counter  by 
choosing  SNMPv2c/SNMPv3  protocols.  This,  however,  may  not  work  because  some 
devices  don't  support  these  protocols. 

> To  switch  to  SNMPv2c/SNMPv3,  you  need  to  manually  customize: 

1 Log  into  the  CP  server  as  cpanel  user. 
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2 Copy  the  default  template  -cpanei/shiva/shiva- 
template s / common/ ds / mrt g_targe t .config  to  the  Custom 
~/shiva/ custom/ shiva- 

templates/common/ds/mrtg_target  .config  location.  Please 
carefully  follow  the  template  customization  procedure  described 
in  Parallels  H-Sphere  Customization  Guide. 

3 Edit  the  first  line  with  ${port}  :${  com_name  }@${device}  : 

according  to  the  MRTG  Reference 
(http://oss.oetiker.ch/mrtq/doc/mrtq-reference.en.html). 

For  example,  to  switch  to  SNMPv2c,  the  line  will  be  like  this: 

Target [${target} ] : <if  config . REVERSE_DEDICATED_SERVER_TRAFFIC 
!=  "TRUE">-</if >$ {port }:${ com  name} @$ {device} ::::: 2 

For  more  advanced  configuration  please  refer  to  MRTG  Reference. 

4 Restart  Parallels  Fl-Sphere  to  apply  customization. 


Chapter  2 2 


System  Packages 


Parallels  H-Sphere  installation  is  modular,  its  packages  independent  and  self- 
configurable.  It  is  possible  to  use  standard  package  managers  (on  page  25)  like  yum, 
up2date  or  apt-get  for  scheduled  updates  of  Parallels  H-Sphere  services,  instead 
of  running  occasional  update  scripts  or  updating  Parallels  H-Sphere  versions. 

In  this  chapter: 


Common  Packages 367 

Parallels  SiteStudio  Packages 396 


Common  Packages 

Common  packages  are  those  used  for  different  types  of  H-Sphere  servers.  For 
example,  hsphere-apache  is  installed  on  Web,  mail,  MySQL  (for  PhpMyAdmin),  and 
PostgreSQL  (for  PhpPgAdmin)  servers;  and  the  hsphere-scripts  package  is  installed  on 
every  Unix  server. 

Below  is  the  reference  on  some  common  packages. 

In  this  section: 

hsphere-info:  Collecting  Information  About  Parallels  H-Sphere  Servers  into  XML  Configs  368 


hsphere-update  Package 369 

Parallels  H-Sphere  Perl  Modules 371 

Parallels  H-Sphere  Apache 375 

Parallels  H-Sphere  PHP 386 
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hsphere-info:  Collecting  Information  About  Parallels  H- 
Sphere  Servers  into  XML  Configs 

Parallels  H-Sphere  includes  the  hsphere-info  package  installed  on  each  Parallels 
H-Sphere  Unix  server.  The  package  installs  the  /hsphere/shared/bin/hsinfo 
script  on  each  server,  and  the  script  collects  information  about  this  server  into  the 

/hsphere/  shared/ etc/ con  fig.  xml  file. 

hsfinfo  Usage: 

hsinfo  [ -ame  ] [ -p  box  IP  ] [ -g  group  ] [ -t  type  ] [ -f  xmlfile  ] [ 

-s  delimiter  ] 

hsinfo  -1  [ -p  box  IP  ] [ -g  group  ] [ -s  delimiter  ] [ -f  xmlfile  ] 

hsinfo  -i  [ -ame  ] [ -g  group  ] [ -f  xmlfile  ] [ -s  delimiter  ] 

hsinfo  -n  [ -p  box  IP  ] [ -g  group  ] [ -f  xmlfile  ] 

hsinfo  -o  a[ddress] |i[nterface] |n [umber]  [ -f  xmlfile  ] 

hsinfo  -d  [ -f  xmlfile  ] 

hsinfo  -v  [ -f  xmlfile  ] 

hsinfo  -G 

hsinfo  -T 

hsinfo  -h  -1  list  of  logical  server  names 

-i  list  of  physical  server  IPs  -n  domain  name  of  the  logical 

server 

-d  servise  zone  name  -p  phisical  box  IP  (default:  local  physical 

box) 

-v  hspere  version 

-a  show  IP  address  -m  show  mask 

-e  show  external  IP  addreyyss 

-o  show  network  interface  name  of  the  physical  IP 
-G  list  of  possible  logical  server  groups 
-T  list  of  possible  IP  types 
-h  help 

by  default  show  only  IP  addresses 

group:  cp,  mail,  unix  hosting,  windows  hosting,  mysql,  pgsql,  mssql, 
dns,  mrtg,  system  (default:  all) 

type:  system,  service,  shared,  dedicated,  resellerSSL,  resellerDNS,  all 
(default:  service) 

xmlfile:  XML  file  location  (default:  /hsphere/shared/etc/conf ig . xml ) 

The  /hsphere/shared/etc/conf ig. xml  file  contains  information  about  physical 
and  logical  server  names,  IDs,  IP  addresses;  system  zones;  current  Parallels  H-Sphere 
version,  etc. 

Download  sample  config.xml  from 

http://download.hsphere.parallels.com/HSdocumentation/xmls/config.xml. 

This  sample  XML  is  for  NAT  configured  Parallels  H-Sphere  cluster  (on  page  28). 
Otherwise,  if  external  IPs  are  used  for  H-Sphere  logical  and  physical  servers,  the  extIP 
attribute  is  omitted,  for  example: 

<ip  type="shared"> 

<addr>ll .22.33. 44</ addr> 

<mask>255 .255.255. 0</mask> 

</ ip> 
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hsphere-update  Package 

The  hsphere-update  package  is  installed  on  each  Parallels  H-Sphere  box.  When 
updating  Parallels  H-Sphere,  it  runs  the  upackages  script  on  the  CP  box  to  update 
Parallels  H-Sphere  packages  on  each  box  to  their  latest  version. 

upackages  Syntax 

upackages  [ — h ] [ — i ] [ -f  ] [ — s ] [ -v  version  ] [ -V  ] [ -e 

show | addrpattern, ... | del rpattern, ... | del : all  ] [ — p ] [ -w  ] [ -m  ] [ - 

j ] [-P]  t-r  ] [ -u  ] [ -P  ] [ -n  ] [ -M  ] [ -S  ] [ -R  ] [ -N  1 [ -I  ] 

[ -o  ] 

Where: 

■ -h  - help  information 

■ -i  - ignore  md5  sum  of  the  downloaded  packages,  only  warning 

■ -f  - force  mode,  update  packages  by  force,  when  md5  sum  of  the  installed  hsphere 
package  differs  from  downloaded  package 

■ -s  - update  only  packages  change,  which  takes  place  in  the  hsphere  subversion 
according  to  corresponding  version 

■ -v  version,  format  U[version]/U[subversion].  If  not  specified, 

/hsphere/ shared/ etc/hsversion  file  is  Checked 

■ -V  - verbose  mode 

■ -e  - [show|add:pattem1,pattern2,...|del:pattern1,pattern2,...|del:all]  - show,  set 
or  delete  a list  of  the  packages  belonging  to  a service  specified  by  pattern 
(patternN),  which  must  be  skipped  during  the  update  on  all  or  particular  HS 
boxes.  The  following  services  (patternN)  are  available  for  excluding:  dns,  mysql, 
postgresql. 

Note:  Use  this  carefully  as  HS  packages  are  connected  with  HS  version.  This  may 
be  used  if  you  have  a customized  version  of  the  specific  HS  package  or  if  you 
update  system  packages,  like  MySQL  server,  via  native  OS  package  manager,  etc. 

For  example: 

hspackages  exclude=add : my sql  ips=192 . 168 . 1 . 10 

■ -p  - PostgreSQL  update  (for  new  HS  box  this  is  done  by  default) 

■ -w  - Site  Studio  update 

■ -m  - MyDNS  service  is  used  instead  of  Bind  9.3.x,  Update  of  the  bind  will  be 
skipped. 

■ -j  - required  during  IP  migration 

■ -r  - package  update  strictly  according  to  package  list  (by  default  update  of  packages 
with  higher  version  skipped) 

■ -t  [php,httpd,ftpd, mysql, pgsql,cphttpd, named]  - place  custom  templates  in  the 
required  location  for  further  editing 

■ -P  - private  update  (for  testing  purpose) 

■ -u  - source  URL  for  packages  download  redefinition 

■ -n  - skip  restart  of  postgres  and  httpdcp  at  the  end  of  update 
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■ -M  - update  modes  (presingle,  hspresingle,  postsingle,  hspostsingle, 
cpinstall,  hsupdate,  postgres,  sitestudio,  update,  ipmigration, 
deploy)  : 

■ presingle  - single  server  package  mode 

■ hspresingle  - 'presingle'  mode,  except  sitestudio  installation 

■ postsingle  - single  server  deploy  mode 

■ hspostsingle  - 'postsingle'  mode,  except  sitestudio  postconf 

■ cpinstall  - control  panel  preinstall  procedure 

■ update  - full  update  (all  packages  update) 

■ hsupdate  - 'update'  mode,  except  sitestudio  update 

■ postgres  - postgres  update 

■ sitestudio  - sitestudio  update 

■ ipmigration  - reconfiguring  IP  dependent  information 

■ deploy  - deploy  mode  (general  box  post-reconfiguration) 

■ -S  - slave  installation/update  mode  - provides  installation/update  of  web  or  mail 
slave  box 

■ -R  mask1[,mask2,...]  - revert  mode,  provides  downgrade  of  a set  of  packages  with 
mask1[,mask2,...] 

■ -N  - this  option  allows  to  force  install/update  for  the  deprecated  OS/soft  listed  in 
http://hsphere.parallels.com/eol.html,  if  possible 

■ -I  - this  option  allows  to  get  exclude  package  list  from  stdin  (used  in  HS  3.1  for 
different  update  profile  configuration  in  CP  interface).  Retrieved  package  list  is 
merged  with  pre-configured  exclude  package  list 

■ -o  - skips  pre-configured  exclude  package  list  during  update 

For  instance,  install  packages  for  Parallels  H-Sphere  2.5  Patch  6 with  md5  sum  of 
the  downloaded  files  ignored: 

upackages  -i  -v  U25 . 0/U25 . 0P6 
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Parallels  H-Sphere  Perl  Modules 

All  necessary  Perl  modules  used  by  Parallels  H-Sphere  on  supported  OS  are  installed 
from  a single  package  hsphere-perl-x-x. 

There  is  no  need  to  update  Parallels  H-Sphere  Perl  modules  by  yourself,  as  when  Perl 
version  is  updated/downgraded,  the 

/hsphere/local/ conf  ig/perl/hspmod.  switch  Utility  is  used  to  switch  Perl  to  a 
proper  Parallels  H-Sphere  Perl  modules  version,  hspmod.  switch  has  the  following 
syntax: 

hspmod . switch  { -1  | -v  perl_version  } 

Where: 

-l  lists  all  possible  Parallels  H-Sphere  perl  module  versions  you  may  switch  to. 

-v  switches  to  the  modules  of  proper  perl_version,  which  must  be  specified  in  0-9.0- 
9.0-9  format. 

The  modules  for  both  native  OS  perl  and  currently  stable  perl  are  included  into  the 
latest  perl  package  update. 

The  following  Perl  modules  are  included  into  the  latest  hsphere-perl  package  and 
installed  to  /hsphere/shared/lib/perl5/  or 
/hsphere/ shared/1 ib/perl5/ site  perl: 

■ Authen-PAM-0.1 5,  http://search.cpan.orq/search?query=Authen- 
PAM&amp;mode=all 

■ Crypt-PasswdMD5-1 .3,  http://search.cpan.org/search ?query=Crypt- 
PasswdMDS&amp;mode=all 

■ DBI-1 .55  http://search.cpan.orq/search?query=dbi&amp;mode=all 

■ DBD-mysql-4.004c,  http://search.cpan.orq/search?query=DBD- 
MvSQL&amp;mode=all 

■ DBD-Pq-1.43,  http://search.cpan.orq/search?query=DBD-MvSQL&amp;mode=all 

■ Diqest-SHA1-2.10,  http://search.cpan.orq/search?query=Diqest- 
SHA1  &amp;mode=all 

■ Diqest-HMAC-1 .01 , http://search.cpan.orq/search?query=Diqest- 
SHA1  &amp;mode=all 

■ Net-IP-1.23,  http://search.cpan.org/search ?query=Net-IP&amp;mode=all 

■ Digest-MD5-2.33,  http://search.cpan.orq/search?query=md5&amp;mode=all 

■ Data-ShowTable-3.3,  http://search.cpan.orq/search?query=Data- 
ShowT  able&amp;mode=all 

■ HTML-Parser-3.56,  http://search.cpan.orq/search?query=html- 
parser&amp;mode=all 

■ HTML-T aqset-3.04,  http://search.cpan.orq/search?query=html- 
taqset&amp:mode=all 

■ MD5-2.03,  http://search.cpan.orq/search?query=md5&amp;mode=all 

■ MIME-Base64-3.05,  http://search.cpan.orq/search?query=Mime- 
Base64&amp;mode=all 

■ Test-Simple-0.70,  http://search.cpan.org/search ?query=Test-Simple&amp:mode=all 
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■ Net-DNS-0.59,  http://search.cpan.orq/search?query=Net-DNS&amp;mode=all 

■ URI-1 .35,  http://search.cpan.prq/search?query=URI&amp;mpde=all 

■ Passwd-1.2,  http://search.cpan.prq/search?query=Passwd&amp;mpde=all 

■ Qupta-1 .5.1 , http://search.cpan.prq/search?query=Qupta&amp;mpde=all 

■ libnet-1 .19,  http://search.cpan.prq/search?query=libnet&amp;mpde=all 

■ libwww-perl-5.803,  http://search.cpan.crq/search  ?query=libwww- 
perl&amp;mcde=all 

■ ParallelUserAgent-2.57, 

http://search.cpan.crq/search  ?querv=ParallelUserAqent&amp;mcde=all 

■ DB  File-1.815,  http://search.cpan.crq/search?query=DB  File&amp;mcde=all 

■ File-Spec-0.87,  http://search.cpan.crq/search?query=File-Spec&amp;mcde=all 

■ Diqest-1 .1 0,  http://search.cpan.crq/search?query=Diqest&amp:mcde=all 

■ PodParser-1.26,  http://search.cpan.crq/search?query=PcdParser&amp:mode=all 

■ Stcrable-2.16,  http://search.cpan.crq/search?querv=Stcrable&amp;mcde=all 

■ Gecqraphy-Countries-1.4,  http://search.cpan.crq/search ?querv=Geoqraphy- 
Countries&amp:mode=all 

■ IP-Ccuntry-2.23,  http://search.cpan.crq/search ?querv=IP-Ccuntry&amp:mcde=all 

■ Net_SSLeay.pm-1.25, 

http://search.cpan.crq/search ?query=Net  SSLeav.pm&amp;mcde=all 

■ IQ-Sccket-SSL-1.06,  http://search.cpan.crq/search ?querv=IO-Sccket- 
SSL&amp;mode=all 

■ Net-ldent-1.20,  http://search.cpan.crq/search?query=Net-ldent&amp:mcde=all 

■ Crypt-OpenSSL-Bignum-10.03,  http://search.cpan.crq/search?querv=Crypt- 
OpenSSL-Biqnum&amp:mcde=all 

■ Crypt-OpenSSL-RSA-O.24,  http://search.cpan.crq/search ?query=Crypt-OpenSSL- 
RSA&amp;mcde=all 

■ MailTccls-1.76,  http://search.cpan.crq/search ?query=MailTccls&amp;mode=all 

■ Mail-DomainKeys-1 .0,  http://search.cpan.crq/search?query=Mail- 
DcmainKevs&amp:mcde=all 

■ Time-HiRes-1 .9707,  http://search.cpan.crq/search?query=Time- 
FliRes&amp:mcde=all 

■ IQ-lnterface-1.03,  http://search.cpan.crq/search ?query=IO-lnterface&amp:mcde=all 

■ Archive-Tar-Wrapper-0.08,  http://search.cpan.crq/search ?query=Archive-Tar- 
Wrapper&amp;mode=all 

■ Archive-Tar-1.30,  http://search.cpan.crq/search ?query=Archive-Tar- 
Wrapper&amp;mode=all 

■ Archive-Zip-1 .18,  http://search.cpan.crq/search?query=Archive-Zip&amp:mcde=all 

■ Ccmpress-Zlib-2.004,  http://search.cpan.crq/search ?query=Ccmpress- 
Zlib&amp:mode=all 

■ Lcg-Lcg4perl-1 .1 0,  http://search.cpan.crq/search?query=Lcq- 
Lcq4perl&amp:mode=all 

■ IO-Zlib-1 .05,  http://search.cpan.orq/search?query=IO-Zlib&amp:mcde=all 

■ Scalar-List-Utils-1 .1 9,  http://search.cpan.crq/search?query=Scalar-List- 
Utils&amp:mcde=all 
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■ XML-SAX-0.15,  http://search.cpan.org/search ?query=XML-SAX&amp;mode=all 

■ XML-Simple-2.1 6,  http://search.cpan.orq/search?query=XML- 
Simple&amp;mode=all 

■ Encode-Detect-1.00,  http://search.cpan.org/search  ?query=Encode- 
Detect&amp;mode=all 

■ Data-Dump-1 .08,  http://search.cpan.org/search ?query=Data-Dump&amp;mode=all 

■ Geo-IP-1.27,  http://search.cpan.orq/search?query=Geo-IP&amp;mode=all 

■ Mail-DKIM-0.24,  http://search.cpan.org/search ?query=Mail-DKIM&amp;mode=all 

To  see  the  list  of  modules  with  their  versions  for  the  specific  hsphere-peri  package, 
run  the  following  command  (specify  the  build  instead  of  x-x): 

rpm  -q  --provides  hsphere-perl-x-  x 

The  above  mentioned  modules  are  installed  with  hsphere-peri  and  required  for 
proper  Parallels  H-Sphere  work. 


WARNING:  Do  not  update  or  change  any  configuration  of  your  system  Perl,  as  it  will 
most  likely  damage  your  Parallels  H-Sphere  installation. 


The  topic  below  provides  the  list  of  supported  Perl  versions. 

In  this  section: 

Supported  Perl  Versions 374 


374  System  Packages 


Supported  Perl  Versions 

Below  is  the  list  of  Perl  packages  required  for  Parallels  H-Sphere  on  supported 
operating  systems.  Please  make  sure  that  your  operating  system  has  the  correct  Perl 
version  installed  according  to  the  following  table. 

To  check  the  version  of  Perl  installed  on  your  box,  run: 

perl  -V 


Operating  System 

Supported  Perl  Versions 

RedHat  EL  3,  CentOS  3.x,  White  Box 

EL  3.x 

Perl  5.8.0;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  4,  CentOS  4.x,  White  Box 

EL  4.x 

Perl  5.8.5;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  4,  CentOS  4.x,  White  Box 

EL  4.x  (x86_64) 

Perl  5.8.5;  5.8.7;  5.8.8;  5.10.0 

RedHat  EL  5,  CentOS  5.x 

Perl  5.8.8;  5.10.0 

RedHat  EL  5,  CentOS  5.x  (x86_64) 

Perl  5.8.8;  5.10.0 

FreeBSD  5.3 

Perl  5.8.5;  5.8.6;  5.8.7;  5.8.8;  5.10.0 

FreeBSD  5.4 

Perl  5.8.6;  5.8.7;  5.8.8;  5.10.0 

FreeBSD  5.5 

Perl  5.8.6;  5.8.7;  5.8.8;  5.10.0 

FreeBSD  6.0 

Perl  5.8.7;  5.8.8;  5.10.0 

FreeBSD  6.1 

Perl  5.8.7;  5.8.8;  5.10.0 

FreeBSD  6.2 

Perl  5.8.7;  5.8;.8  5.10.0 
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Parallels  H-Sphere  Apache 

In  Parallels  H-Sphere  3.1  Beta  1 the  Web  service  functionality  was  greatly  extended 
and  improved  to  allow  for  more  flexibility  both  in  administering  Unix  web  boxes  and  in 
end  user  Web  settings. 

This  chapter  describes  the  main  features  of  the  Web  service  software  and  includes 
information  on  Apache  configuration  useful  for  Parallels  H-Sphere  system 
administrators. 

In  this  section: 


Web  Service  Packages 375 

Support  of  Apache  2.2.x  and  1 .3.x 376 

Tuning  Web  Service  from  the  CP  Interface 377 

Apache  Modules 380 

Apache  Configuration 383 

Web  Statistics  Software 385 

Apache  Logs  and  Web  Traffic  Calculation  in  Parallels  H-Sphere 385 

Log  Rotate  Config  File 385 

Apache  Suexec 386 


Web  Service  Packages 

Apache  2.2  underwent  significant  changes  since  1 .3  version.  Accordingly,  there  are 
PHP  modules  compatible  with  each  particular  Apache  version  that  is  indicated  in  the 
name  of  PHP  package  (lx  or  2x).  The  cgi/cii  part  of  PHP  is  assembled  and  works 
based  on  Apache  1 .3.  Only  the  pear  part  of  PHP  is  common  for  the  two  Apache 
versions. 

Here  is  the  list  of  web  service  software  packages  for  Parallels  H-Sphere  3.1  Beta  1 and 
up  (note  that  versions  are  just  examples  that  may  differ  from  current  ones): 


Package 

Description 

hsphere-apache2-h3 .1-2.2. 6-x 

Apache  2.2.x  binaries,  modules,  libraries 
and  headers 

hsphere-apache-h3 .1-1.3. 39-x 

Apache  1.3.x  binaries,  modules,  libraries 
and  headers 

hsphere-apache-shared-h3 . 1- 

1 — X 

Configuration  template  files,  scripts,  startup 
files,  etc.  common  for  Apache  1 .3.x  and 

2.2.x 

hsphere-apache-utils-h3 . 1-1- 

X 

Utilities  used  when  parsing  apache  logs, 
lynx  browser,  etc. 

hsphere-php4-lx-4 . 4 . 7-x 

Iibphp4  for  Apache  1 .3.x 

hsphere-php4-2x-4 . 4 . 7-x 

Iibphp4  for  Apache  2.2.x 

hsphere-php4-cgi-4 . 4 . 7-x 

CLI  and  CGI  php4  binaries 

hsphere-php4-pear-4 . 4 . 7-x 

PEAR  for  PHP4 
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hsphere-php4-plugins-4 . 4 . 7-x 

Set  of  plugins,  their  confs,  which  may  work 
in  pair  with  CLI,  CGI  or  Iibphp4 

hsphere-php5-lx-5 . 2 . 4-x 

Iibphp5  for  Apache  1 .3.x 

hsphere-php5-2x-5 . 2 . 4-x 

Iibphp5  for  Apache  2.2.x 

hsphere-php5-cgi-5 . 2 . 4-x 

CLI  and  CGI  php4  binaries 

hsphere-php5-pear-5 . 2 . 4-x 

PEAR  for  PHP5 

hsphere-php5-plugins-5 . 2 . 4-x 

Set  of  plugins,  their  confs,  which  may  work 
in  pair  with  CLI,  CGI  or  Iibphp5 

Support  of  Apache  2.2.x  and  1.3.x 

In  addition  to  Apache  1 .3.x,  support  of  Apache  2.2.x  is  implemented.  There  are  two 
modes  of  Apache  2.2.x: 

■ MPM  prefork  (http://httpd.apache.Org/docs/2.2/mod/prefork.html) 

■ MPM  worker  (http://httpd.apache.Org/docs/2.2/mod/worker.html) 

For  the  MPM  worker  mode,  cgi  requests  are  processed  via  mod_cgid. 
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Tuning  Web  Service  from  the  CP  Interface 

In  Parallels  H-Sphere  3.1  Beta  1 and  up  there  is  a possibility  to  choose  some  Web 
settings  for  a physical  Web  server  right  from  administrator's  cp  interface: 

■ switch  between  Apache  versions 

Note:  this  setting  is  available  for  all  physical  boxes. 

■ enable  additional  Apache  modules 

■ when  enabling  apache_security  module,  set  also  mod_security  options 

■ set  PHP  configuration 

■ when  enabling  fastcgi  mode,  configure  its  VirtualHost  options 

■ disable  unnecessary  PHP  plugins 

Note:  For  more  detailed  information,  refer  to  section  Advanced  Web  Server  Settings  of 
Parallels  H-Sphere  Service  Administrator  Guide. 


All  webbox  related  settings  chosen  from  the  cp  interface  are  stored  in  the  following  file: 

/hsphere/ shared/ scr ip ts/scr ip ts.cfg 

Such  changes  are  applied  immediately  by  the  script: 

/hsphere/shared/scripts/manage-service . sh  httpd  restart 

The  settings  are  stored  in  the  configuration  file  in  the  form  of  'prefix_titie=vaiue. 
There  are  several  groups  of  settings: 

In  this  section: 
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Apache  Settings 

These  are  settings  for  enabling/disabling  Apache  modules.  The  prefix  is  apache.  Here 
is  the  list  of  possible  settings: 


Title 

Default  Value 

Comments 

apache  libphp 

4 

1 

apache  libphp 

5 

0 

apache_ssl 

1 

apache_scgi 

0 

apache_frontp 

age 

0 

Ignored  in  Apache  2 
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apache_throttl 

e 

0 

Ignored  in  Apache  2 

apache_status 

0 

apache_fastcgi 

0 

apache_securit 

y 

0 

apache_cache 

0 

apache  securit 
y2 

0 

Ignored  in  Apache  1 

apache_versio 

n 

1 

Apache  version.  Only  for  Apache  2. 

apache_mpm 

prefork 

MPM  mode:  prefork  or  worker.  Only  for 
Apache  2 

All  independent  modules  are  implemented  via  specific  templates  each  allowing  for 
customization.  They  have  their  own  config  files  which  are  inserted  in  the  main  config  file 
using  the  include  directive.  The  main  config  file  is  also  realized  via  independent 
templates  for  Apache  1 .3.x  and  2.2.x. 

PHP  Settings 

For  each  Apache  version/mode  (Apache  1 .3.x  or  2.2.x  MPM  prefork  and  MPM  worker) 
there  is  a possibility  to  operate  PPIP  in  6 modes:  libphpS,  iibphp4,  cgi-php5, 
cgi-php4,  f astcgi-php4 , f astcgi-php5.  The  prefix  is  ' php  '.  Here  is  the  list 
of  possible  settings: 


Title 

Default  Value 

Comments 

php  libph 
p4 

2 

php_fastc 

gi4 

0 

Needs  mod  fastcgi  being  enabled  for  Apache 

php_cgi4 

1 

phpjibph 

0 

If  the  value  is  other  than  o,  the  value  for  php  libphp4  has 

p5 

to  be  0 

php_fastc 

gi5 

2 

php_cgi5 

1 
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Fastcgi  Settings 

Fastcgi  (http://www.fastcgi.com/mod  fastcq i/docs/mod  fastcqi.htm),  unlike  the  regular 
cgi,  keeps  the  activated  module  e.g.  php  loaded  for  some  time  after  the  call.  All  further 
calls  are  carried  out  quicker  that  preserves  time  for  programs  being  loaded.  However, 
the  number  of  programs  that  can  be  stored  in  the  fastcgi  operating  memory  is 
limited. 

All  programs  loaded  by  fastcgi  are  performed  with  the  privileges  of  the  user  who 
owns  the  corresponding  virtual  host.  That  is  why  they  can  only  serve  calls  to  this 
particular  virtual  host.  This  means  that  if  all  users  will  have  fastcgi,  this  may  cause 
considerable  delays  and  enormous  increase  in  server  load. 

We  recommend  selective  approach  to  enabling  fastcgi,  i.e.  after  enabling  it  for 
heavily  visited  virtual  hosts  monitor  the  server  load  for  several  days.  If  after  such 
monitoring  the  load  is  found  permissible,  enable  fastcgi  for  more  users  and  so  on. 

The  same  is  with  with  fastcgi  parameters.  They  are  set  on  the  server  level  and  can't 
be  changed  for  a particular  virtual  host.  There  is  not  direct  way  to  check  effectiveness 
of  these  parameters  - only  indirect  observance  based  on  server  operating.  That  is  why 
change  these  parameters  with  precaution. 


The  prefix  is  ' fcgi_' . Here  is  the  list  of  possible  settings: 


Title 

Default  Value 

Comments 

autollpdate 

There  may  be  a serious  problem  when 
this  option  is  used  with  -restart. 

flush 

0 

gainValue 

0.5 

idle-timeout 

30 

[seconds] 

initial-env 

FCGI  ROL 

E 

Allows  to  check  which  fastcgi  setting  is 
being  used.  RubyOnRails  may  need 
additional  variables. 

init-start-delay 

1 [seconds] 

killlnterval 

300 

[seconds] 

listen-queue- 

depth 

100 

maxClassProces 

ses 

10 

It  must  be  <=  to  -maxProcesses  (this  is 
not  programmatically  enforced) 

maxProcesses 

50 

It  must  be  >=  to  -maxClassProcesses  (this 
is  not  programmatically  enforced) 

minProcesses 

5 

multiThreshold 

50 

If  only  one  instance  remains, 
singleThreshold  is  used  instead 
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pass-header 

This  option  makes  available  the  contents 
of  headers  which  are  normally  not 
available  (e.g.  Authorization) 

priority 

0 

processSlack 

5 

restart 

Causes  the  process  manager  to  restart 
dynamic  applications  upon  failure  (similar 
to  static  applications) 

restart-delay 

5 [seconds] 

singleThreshold 

0 

Changing  this  is  not  recommended 
(especially  if  -appConnTimeout  is  set) 

startDelay 

3 [seconds] 

Must  be  less  than  appConnTimeout  to 
be  effective 

updatelnterval 

300 

[seconds] 

Apache  Modules 

The  core  of  hsphere-apache  contains  only  two  modules:  http  core . c and 
mod_so . c.  The  rest  are  compiled  as  DSO,  and  their  list  can  be  obtained  by  running: 

■ for  Apache  1 .3: 

Is  /hsphere/ shared/ apache/libexec/ 

■ for  Apache  2.2: 

Is  /hsphere/ shared/ apache2/modules/ 

Modules  in  different  Apache  versions  may  have  distinction  in  their  titles  and 
configuration  directives.  Apache  2.2  lacks  some  modules  present  in  1.3  version,  their 
functionalities  being  substituted  by  other  modules,  except  for  mod_throttie  and 
mod_f  rontpage  which  are  not  supported  in  2.2  version. 

Compatibility  of  Apache  1 .3  and  2.2  is  achieved  in  Parallels  H-Sphere  via  the 
mod_macro  module.  Apache  2.2  adds  several  new  modules  to  extend  functionality. 

See  below  the  comparative  list  of  modules  (the  titles  correspond  to  *.so  files): 


Apache  1.3 

Apache  2.2 

Iibphp4* 

Iibphp4* 

Iibphp5** 

Iibphp5** 

libproxy*** 

libssl 

mod_ssl 
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mod_access 

mod_actions  mod_actions 

mod_alias  mod_alias 

mod_asis 

mod_auth 

mod_auth_anon 

mod_auth_basic 

mod_auth_db 

mod_auth_dbm  mod_authz_dbm 

mod_auth_digest 

mod_auth_external  mod_authnz_extern 
al 

mod_auth_kerb  mod_auth_kerb 

mod_authn_anon 

mod_authn_dbd 

mod_authn_dbm 

mod_authn_default 

mod_authn_file 

mod_authz_default 

mod_authz_groupfil 

e 

mod_authz_host 

mod_authz_owner 

mod_authz_user 

mod_autoindex  mod_autoindex 

mod  cache 


mod_cern_meta  mod_cern_meta 

mod_cgi  mod_cgi 


mod_digest 

mod  dir  mod  dir 


mod_disk_cache 

mod_dumpio 


mod_env  mod_env 

mod_expires  mod_expires 

mod_ext_filter 

m od_ext  ract_f  o rwar  m od_ext  ract_f  o rwar 
ded  ded 

mod_fastcgi  mod_fastcgi 

mod_filter 

mod_frontpage 

mod_gzip 

mod_headers  mod_headers 

modjdent 
modjmagemap 

modjmap 

modjnclude  modjnclude 

modjnfo  modjnfo 

mod_log_agent 

mod_log_config  mod_log_config 

mod_log_forensic  mod_log_forensic 

mod_log_referer 

modjogio 

mod_macro  mod_macro 

mod_mem_cache 

mod_mime  mod_mime 

mod_mime_magic  mod_mime_magic 

mod_mmap_static 

mod_negotiation  mod_negotiation 

mod_psoft_traffic 

mod_rewrite  mod_rewrite 

mod_scgi  mod_scgi 

mod_security  mod_security 

mod_security2 
mod_setenvif  mod_setenvif 

mod_speling  mod_speling 

mod_status  mod_status 

mod_suexec 

mod  throttle 


mod_unique_id 

mod_unique_id 

mod_userdir 

mod_userdir 

Notes: 

*Part  of  the  hsphere-php5 -Xx-<PHPVER>  package  where  X is  apache  version  (1  or 
2). 

**Part  of  the  hsphere-php4-Xx-<PHPME/?>  package  where  X is  apache  version  (1  or  2). 
***This  module  provides  for  an  HTTP  1.1  caching  proxy  server. 


Apache  Configuration 


Apache  1.3 

Apache  2.2 

/hsphere /shared/ apache 

/hsphere/ shared/ apache2 

Comments:  Apache  home  directory 

/hsphere /local /config /httpd 

/hsphere /local/ conf ig/httpd2 

Comments:  Apache  configuration  directory 

~httpd/conf  -> 

/ hsphere / local/ con fig/httpd 


Comments:  The  symlink  from  home  directory 

Configuration  File 

/hsphere /local/ conf ig/httpd/httpd  /hsphere /local/ conf ig/httpd2 /httpd 

.conf  .conf 

Comments:  This  file  contains  server  wide  configuration  (modules  enabled,  their  parameters 
set  etc.).  We  don't  recommend  that  changes  are  made  to  this  file. 

When  Apache  modules  are  enable/disabled  from  the  interface,  the  configuration  files  are  left 
unchanged.  This  interface  feature  is  implemented  via  the  comand  line  Apache  using 
<if Define  . . . > directives  and  corresponding  global  symbols. 

These  files  are  customized  using  config  file  templates. 

More  on  config  file  template  customization  read  in  Appendix  C of  Parallels  H-Sphere 
Installation  Guide. 

Custom  Configuration  File 

/ hsphere / 1 ocal / con f ig/ httpd/ cus to  / hsphere /local/ conf ig/httpd2 /cus to 

m.conf  m.conf 

Comments:  We  recommend  that  this  file  is  used  for  making  changes  to  the  wide 
configuration,  and  for  enabling  additional  modules  in  particular.  This  may  facilitate  finding 
configuration  errors  in  case  the  server  cannot  start. 

When  Apache  is  launched,  the  custom  configuration  file  is  the  second  to  be  processed  after 
httpd . conf.  After  that,  virtual  hosts  configuration  is  picked  up. 


System  Virtual  Hosts  Config 

/hsphere/ local/ conf ig/httpd/ naraev  /hsphere/ local/ config /httpd2 / naraev 

h.conf  h.conf 

Comments:  This  file  contains  list  of  all  system  (not  user!)  virtual  hosts.  Apache  supports 
virtual  host  of  3 types  - name-  based,  IP-based  and  port-based.  Parallels  H-Sphere  uses 
name-based  virtual  hosts  by  default  but  the  other  types  can  be  used  as  well.  The 
configuration  file  contains  information  on  host  type  for  each  IP.  This  file  is  processed  after 
custom,  conf  but  before  processing  the  configuration  of  virtual  hosts. 

Virtual  Hosts  (Logical  Servers)  Configs 

/hsphere /local/ conf ig/httpd/ conf/  /hsphere /local/ conf ig/httpd2 / conf/ 

lservers/  lservers/ 

mail. conf,  mrtg.conf,  mail. conf,  mrtg.conf, 

mysql . conf . . . mysql . conf . . . 

Comments:  For  each  logical  server  a virtual  host  is  created.  Before,  when  accessing  the  box 
by  its  logical  name  it  was  possible  to  view,  for  instance,  sources  of  phpMyAdmin.  Now  with 
each  logical  name  having  its  own  virtual  host  such  a possibility  is  eliminated. 

These  files  are  customized  using  templates. 

More  on  config  file  template  customization  read  in  Appendix  C of  Parallels  H-Sphere 
Installation  Guide. 


/hsphere /local /conf ig/httpd/ sites/ 

Comments:  This  directory  contains  files  for  user  virtual  hosts.  A link  to  this  directory  is 
included  to  the  configuration  directory  of  Apache  2.2.  This  means  that  configuration  files  of 
user  virtual  host  are  common  for  the  two  Apache  versions. 

Syntactical  differences  in  directives  between  1.3  and  2.2  versions  are  leveled  by  mod  macro 
module  introduced  in  Parallels  H-Sphere  3.1  and  up,  i.e.  macros  are  used  instead  of 
configuration  directives,  mod  macro  is  a third-party  module  to  the  Apache  Http  Server 
distributed  with  a BSD-style  license  like  Apache.  It  allows  the  definition  and  use  of  macros 
within  Apache  runtime  configuration  files.  The  syntax  is  a natural  extension  to  apache  html- 
like  configuration  style. 

Macros  are  placed  to  . /macro  of  the  Apache  configuration  directory.  Macros  for  Apache  1 .3 
are  different  from  those  for  Apache  2.2. 
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Web  Statistics  Software 
Apache  2.2.x 

General  web  statistics  is  gathered  using  general  mod_iog_conf  ig  and  mod  iogio 
modules.  mod_iog_config  is  patched  to  provide  logging  to  the  server  log  even  if 
custom  logs  are  redefined  at  the  virtual  host  level.  For  this  purpose, 
AlwaysServerLogs  directive  is  added. 

Apache  1.3.x 

General  web  statistics  is  gathered  using  the  mod_psoft_traf f ic  apache  module. 

Apache  Logs  and  Web  Traffic  Calculation  in  Parallels  H-Sphere 

Apache  logs  are  located  in  the  /hsphere/iocai/var/httpd/iogs/  directory.  Also, 
each  hosted  Web  domain  has  its  own  logs  in  the 

/hsphere / local  /home /<user> / logs  / <domain.name> / directory  (see  Web  traffic 
calculation  (on  page  133)). 

There  are  two  types  of  Web  traffic  calculation  in  Parallels  H-Sphere: 

■ third-party  traffic  calculation  - Parallels  Pi-Sphere  writes  traffic  log  files  to  each 
domain's  directory  to  make  them  available  for  third-party  log  analyzers:  Webalizer, 
Modlogan,  and  AWStats 

■ Parallels  Pi-Sphere  built-in  traffic  calculation  - Parallels  Pi-Sphere  provides  its  own 
mechanism  of  traffic  calculation  used  in  billing. 

Please  refer  to  a separate  section  on  Web  traffic  calculation  and  log  rotation  (on  page 
133). 

Log  Rotate  Config  File 

/hsphere/local/ conf  ig/httpd/ rotatelog . cf g - log  rotate  COnfig  file  which 
includes  all  log  confs  located  in  the 

/hsphere/local/  conf  ig/httpd/ logrotate_conf  / directory: 

■ <domain.name>  .transferiog  .conf  - config  file  for  transfer  log  rotation  for  a 
domain 

■ <domain.name> . erroriog . conf  - config  file  for  error  log  rotation  for  a domain 

■ <domain.name> . agentiog . conf  - config  file  for  agent  log  rotation  for  a domain 

■ <domain.name> . ref  erreriog . conf  - config  file  for  referrer  log  rotation  for  a 
domain 
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Apache  Suexec 

Parallels  H-Sphere  WebBox  Apache  suexec  is  configured  to  run  users'  CGI  scripts  only 
within  the  /hsphere/iocai/home/  directory,  recursively.  Thus,  a user  may  run 
his/her  own  cgi  scripts  only  it  he/she  has  fourth  nesting  level  within  the  Parallels  Pi- 
Sphere  user  home  directory,  for  example,  /hsphere/iocai/home/user_homei. 

Parallels  H-Sphere  PHP 


PHP  is  assembled  into  separate  Parallels  H-Sphere  packages: 


Package 

Description 

hsphere-php4  - lx-<ves/on> 

Iibphp4  for  Apache  1 .3.x 

hsphere-php4  -2x-<ves/Of)> 

Iibphp4  for  Apache  2.2.x 

hsphere -php4- cgi -<ves/’on> 

CLI  and  CGI  php4  binaries 

hsphere-php4-pear-<ves/on> 

PEAR  for  PHP4 

hsphere-php4 -plugins -<vesion> 

Set  of  plugins,  their  confs,  which  may  work  in 
pair  with  CLI,  CGI  or  Iibphp4 

hsphere -php5-lx-<  vesion> 

Iibphp5  for  Apache  1 .3.x 

hsphere-php5 -2  x-<vesion> 

Iibphp5  for  Apache  2.2.x 

hsphere -php5-  cgi -<vesion> 

CLI  and  CGI  php4  binaries 

hsphere-php5-pear -<vesion> 

PEAR  for  PHP5 

hsphere -php5 -plugins -<vesion> 

set  of  plugins,  their  confs,  which  may  work  in 
pair  with  CLI,  CGI  or  Iibphp5 

In  this  section: 


Configuring  PHP  from  the  Interface 387 

PHP  Components 387 

Objects  in  PHP  5 387 

PHP  Test  Page 388 

Customizing  php.ini  Configuration  File 388 

PHP  Modules  Installed  with  Parallels  H-Sphere  PHP  Packages 388 

Configuring  PHP  Safe  Mode 393 

Adding  PHP  Extensions 394 
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Configuring  PHP  from  the  Interface 

In  Parallels  H-Sphere  3.1+  administrators  have  more  capacity  in  configuring  PHP  while 
users  can  choose  between  PHP  4 and  5.  Please  refer  to  the  section  on  Apache  in 
Parallels  H-Sphere  3.1+  (on  page  375)  where  this  functionality  is  described. 

PHP  Components 
Ldap 

Ldap  support  has  been  included  to  php-core,  which  is  one  of  the  reasons  why  horde 
may  start  to  slow  down  when  sending  mail.  It  happens  because  horde  is  trying  to 
connect  to  available  ldap  servers  that  are  very  slow  by  themselves. 

Pear 

Another  important  peculiarity  of  the  new  PHP  packages  is  support  of  pear.  To  view 
which  packages  from  pear  repository  have  been  installed,  run: 

/hsphere/shared/phpX/bin/pear  list 

To  view  the  list  of  all  pear  packages  available  in  the  repository,  run: 

pear  list-all 

To  check  which  pear  packages  need  to  be  upgraded,  run: 

pear  list-upgrades 

To  upgrade  all  pear  packages  installed,  run: 

pear  upgrade -all 

Peel 

As  for  the  PECL  repository,  2 packages  from  it  (Fileinfo  and  SQLite)  have  been 
included  to  PHP4  and  one  (Fileinfo)  to  PHP5.  In  PHP5,  SQLite  is  supported  from  php- 
core. 

Objects  in  PHP  5 

PHP5  has  undergone  some  principal  changes  in  the  way  it  works  with  objects.  That  is 
why  some  programs  that  work  fine  with  PHP4  may  not  work  with  PHP5.  To  ensure 
PHP5  support,  all  third-party  products  included  to  Parallels  H-Sphere  have  been 
updated  to  the  latest  available  version. 
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PHP  Test  Page 

New  PHP  packages  have  been  assembled  to  perfectly  fit  mail  web-interfaces,  and 
horde  in  particular.  This  means  that  PHP  test  page  can  be  obtained  from 
http:/<box_/P>/horde/test.php.  Here,  pay  attention  to  memory_iimit  value.  We 
recommend  that  it  is  either  -1  (disabled)  or  8 MB. 


Customizing  php.ini  Configuration  File 

If  you  want  to  customize  PHP  config  files  for  PHP  4 and  PHP  5,  please  refer  to 
Appendix  C.  Customizing  Server  Configuration  Files  By  Means  of  Templates  of 
Parallels  H-Sphere  Installation  Guide. 

PHP  Modules  Installed  with  Parallels  H-Sphere  PHP  Packages 


Standard  PHP  Installation  has  the  following  modules  enabled: 


PHP  extensions 

php4 

php5 

before  4.4.4 


4.4.4+ 


before  5.1.6 


5.1.6+ 


bcmath 

so 

so 

so 

so 

bz2 

so 

core 

so 

core 

calendar 

so 

so 

so 

so 

ctype 

core 

core 

core 

core 

curl 

so 

so 

so 

so 

date 

- 

- 

core 

core 

dba 

core 

core 

core 

core 

dbase 

so 

so 

so 

so 

dbx 

so 

so 

- 

- 

dom 

- 

- 

core 

core 

domxml 

so 

so 

- 

- 

exit 

so 

so 

- 

so 

fileinfo 

so 

so 

so 

so 

filepro 

so 

so 

so 

* 

ftp 

so 

core 

so 

core 

gd 

so 

core 

so 

core 

gettext 

so 

core 

so 

core 

gmp 

so 

so 

so 

so 

hash 

- 

- 

core 

core 

iconv 

so 

so 

so 

so 

imap 

so 

so 

so 

so 

Idap 

core 

so 

core 

so 

libxml 

- 

- 

core 

core 

mbstrlng 

core 

core 

core 

core 

meal 

so 

so 

- 

* 

mcrypt 


so 


core 


so 


core 


mhash 

so 

core 

so 

core 

mime_magic 

core 

core 

core 

core 

mnogosearch 

so 

so 

so 

so 

mysql 

so 

so 

so 

so 

mysqli 

- 

- 

- 

so 

n curses 

so 

so 

so 

so 

odbc 

so 

so 

so 

so 

openssl 

core 

core 

core 

core 

overload 

core 

core 

- 

* 

pcntl 

so 

so 

so 

so 

pdf 

so 

so 

- 

- 

pcre 

core 

core 

core 

core 

PDO 

- 

- 

core 

core 

pgsql 

so 

so 

so 

so 

posix 

core 

core 

core 

core 

pspell 

so 

so 

so 

so 

Reflection 

- 

- 

core 

core 

session 

core 

core 

core 

core 

shmop 

so 

so 

so 

so 

SimpleXML 

- 

- 

core 

core 

soap 

- 

- 

so 

so 

sockets 

core 

core 

so 

core 

SPL 

- 

- 

core 

core 

sqlite 

so 

so 

core 

so 

standard 

core 

core 

core 

core 

swf 


removed 


so 

sysvmsg 

so 

sysvsem 

so 

sysvshm 

core 

tokenizer 

core 

xml 

so 

xmlrpc 
xmlreader 
xml  writer 


so 

xslt 

so 

yp 

so 

zip 

core 

zlib 


so 

so 

so 

so 

so 

so 

so 

so 

so 

core 

core 

core 

core 

core 

core 

so 

so 

so 

- 

core 

core 

- 

core 

core 

- 

core 

core 

so 

- 

- 

so 

- 

* 

core 

- 

- 

core 


core 


core 
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Detailed  information  on  PHP  modules  find  in  PHP  Manual, 
http://www.php.net/manual/en/ 


Notes: 


■ meal  extension  has  been  moved  to  the  PECL  repository  (http://pecl.php.net/)  and  is 
no  longer  bundled  with  PHP  as  of  version  5.0.0. 

■ yp  extension  has  been  moved  to  the  PECL  repository  and  is  no  longer  bundled  with 
PHP  as  of  version  5.1.0. 

■ filepro  extension  has  been  moved  to  the  PECL  repository  and  is  no  longer  bundled 
with  PHP  since  version  5.2.0. 

■ overload  extension:  see  the  page 

http://www.php.net/manual/en/lanauaqe.oop5.overloading.php  for  more  information. 


PHP  Modules  Default  Location 

To  check  php  modules  default  location,  run: 

# /hsphere/ shared/php/ <PHPVERSION> /bin/php-conf ig  --extension-dir 

This  directory  is  linked  to  hsphere  catalogue  structure 

/hsphere/ shared/ apache/libexec/ php<PHPVERSION>ext 

To  list  installed  so-modules,  run: 

# Is  /hsphere/shared/apache/libexec/php<PHPVERSION>ext/* . so 

Enabling/Disabling  PHP  Modules 

Modules  are  added  one  by  one  with  ini-files  of  the  same  name  that  can  be  found  in 

/hsphere/local/ conf  ig/httpd/php <PHPVERSION> / php . d 

If  an  ini-file  contains  extension=extname . so  line,  php  at  startup  loads  a 
corresponding  extension  module.  Mind,  any  text  following  an  unquoted  semicolon  is 
ignored,  thus  the  module  indicated  in  the  line;  extension=extname . so  won't  load. 

At  updates  coming  after  hsphere-php4-4.4.4-2  ini-files  are  not  overwritten  (as  in  earlier 
versions),  but  remain  unchanged.  Only  for  extensions  that  do  not  have  corresponding 
ini-file,  ini-files  are  created  according  to  the  procedure  above. 

php.info 

php. info  gathers  info  on  php  core,  modules,  apache  environment  etc.  You  can  run  it  as 
console  command: 

/hsphere/shared/php4/bin/php-cli  -i  | less 
or  screen  its  output  at  http://<box_ip>/hsphpinfo.php 
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Configuring  PHP  Safe  Mode 


Important:  PHP  safe  mode  is  not  supported,  you  can  use  it  at  your  own  risk. 


PHP  safe  mode  is  turned  off  by  default  in  the  original  Parallels  H-Sphere  configuration. 

To  turn  it  on,  set  safe_mode=On  in  the  php . ini  file  (usually,  in  the 

/us  r/ local /lib  directory).  Please  note  that  php. ini  must  be  customized  by  means  of 

the  respective  custom  config  file  template. 

> To  use  default  Parallels  H-Sphere  configuration  for  PHP  with  safe  mode  on: 

1 Take  the  default  php . ini  installed  with  standard  Parallels  H-Sphere 
PHP  packages. 

2 Turn  the  safe  mode  on. 

3 Copy  that  file  to  the  PHP  installation  directory  (usually, 

/usr/ local/ lib). 

Read  more  on  PHP  safe  mode  configuration  in  PHP  documentation 
(http://www.php.net/manual/en/features.safe-mode.php#ini.safe-mode). 

To  turn  the  safe  mode  off  for  an  individual  account,  edit/add  the  following  directives  in 

the  /hsphere/iocal/ conf ig/httpd/httpd.  conf  Apache  configuration  file  on  the 
Web  server. 

<Di rectory  / hsphere/iocal/ home /wwwuser> 

<IfModule  mod_php4.c> 

php  admin  flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin  value  session . save_path  "/tmp" 

</IfModule> 

<IfModule  mod_php5.c> 

php  admin  flag  safe  mode  off 

php  admin  value  upload  tmp  dir  "/tmp" 

php  admin  value  session . save_path  "/tmp" 

</IfModule> 

</Directory> 

To  have  IMP  Horde  web  mail  (on  page  150)  working  when  the  safe  mode  is  on,  set  the 
following  directive  in  /hsphere/iocal/  conf  ig/httpd/httpd  .conf  on  the  Web 

server  and  make  changes  in  the  respective  custom  configuration  file  template): 

<Directory  /hsphere/ shared/ apache/htdocs/horde> 

<IfModule  mod_php4.c> 

php  admin  flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

<IfModule  mod_php5.c> 

php  admin  flag  safe  mode  off 

php  admin  value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

</Directory> 


394  System  Packages 


To  configure  Webshell  4 (on  page  126)  so  that  it  would  work  with  the  safe  mode 
globally  on: 

<Directory  /hsphere/ shared/ apache/htdocs/webshell4> 

<If Module  mod_php4.c> 

php  admin^flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</ IfModule> 

<If Module  mod_php5.c> 

php  admin  flag  safe  mode  off 

php  admin_value  upload  tmp  dir  "/tmp" 

php  admin_value  session . save_path  "/tmp" 

</  IfModuleX/Directory> 

Restart  Apache  (on  page  55)  after  performing  necessary  modifications. 

Adding  PHP  Extensions 

PHP  4 and  PHP  5 packages  include  almost  all  commonly  used  extensions.  So,  before 
you  start  re-compiling  PHP,  make  sure  that  an  extension  you  need  to  add  is  indeed 
absent.  See  the  list  of  modules  included  in  PHP  4 and  PHP  5 (on  page  388). 

in  this  section: 
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Compilation  Requirements 

Before  the  compilation,  check  that  the  following  libraries  are  installed: 

■ autoconf 

■ automake 

■ libtool 

■ zlib-devel 

■ mysql-devel 

■ postgresql-devel 

Other  required  libraries  are  listed  in  the  documentation  to  respective  modules. 

Please  also  take  into  account  that  PHP  4 and  PHP  5 have  different  module  structures. 
For  example,  the  domxml  module  of  PHP  4 is  absent  in  PHP  5. 
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Adding  New  Extensions 

PHP  packages  are  built  from  modules.  To  include  a new  module,  use  phpize  in  the 
following  way: 

# tar  zxf  your_module.tgz 

# cd  your_module 

# /hsphere/ shared/php4/bin/phpize 

# . /configure  --with-php-conf ig=/hsphere/shared/<PHP\/£RS/OA/>/bin/php- 
conf ig 

# make 

# make  install 

<PHPVERSION>  is  php4  or  php5,  depending  on  PHP  version. 

To  find  out  where  a new  extension  is  compiled  to  and  where  all  other  PHP  extensions 
are  located,  run: 

# /hsphere/shared/<PHPVERSION>/bin/php-conf ig  --extension-dir 

Aslo  you  can  use  additional  options  in  configuration  string,  for  example: 

. /configure  --with-php-conf ig=/hsphere/shared/php4/bin/php-conf ig  -- 
with-mssql=/usr/ local /freetds  -- enable -msdblib 


Adding  PEAR  Modules 

To  install  PEAR  modules,  run: 

# /hsphere/shared/<PHPVERSION>/bin/pear  install  your_module 

Read  the  PEAR  Command  line  installer 

(http://pear.php.net/manual/en/installation.cli.php)  documentation  for  details. 


Adding  PECL  Modules 


PECL  modules  can  be  installed  either  by  phpize  or  by  pear.  See  Installation  of 
PECL  extensions  (http://www.php.net/manual/en/install.pecl.php)  in  PHP  Guide. 
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Enabling/Disabling  Built-in  PHP  Modules 

Modules  that  are  installed  with  PHP  packages  are  enabled  by  default. 

> To  disable  (or  enable)  a module: 

1 Go  to  the  directory  where  respective  .ini  file  for  a module  is  located: 

# cd  /hsphere/local/config/httpd/<P/-/Pt/ERS/OA/>/php  .d/ 

Here,  <PHPVERSION>  is  php4  or  php5. 

2 Open  the  <module_name> . ini  file  for  edit.  See  the  list  of  PHP  modules 
(on  page  388). 

3 Comment  the  line  extension=<module_name> . so  to  disable  the 
module: 

; extension=<module  name>.so 

Uncomment  this  line  to  enable  the  module. 

4 Restart  Apache  (on  page  55)  on  the  Web  server  to  apply  changes. 


Parallels  SiteStudio  Packages 

Parallels  SiteStudio  is  installed  in  two  separate  Parallels  H-Sphere  packages: 

■ hsphe  re  -sitestudio- core -<version> 

hsphere-sitestudio-templates-<vers/07J>  To  install  Parallels  SiteStudio 
packages,  go  to  /hsphere/instaii  and  run: 

make  ss-install 

This  command  launches  the  script  which  downloads  and  installs  the  necessary 
packages  (e.g.  xorg-xii-libs)  and  then  installs  Parallels  SiteStudio. 

Imaker  is  run  under  the  imaker  user  (not  root!). 

If  previous  Parallels  SiteStudio  version  was  installed  from  a . tgz  archive,  the  new  one 
is  installed  over  it  without  uninstalling  the  older  version. 
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Load  Balancing 


It  is  possible  to  add  load  balanced  (LB)  Web  and  mail  clusters  to  Parallels  H-Sphere. 
Load  balancing  implies  balancing  server  traffic  amongst  multiple  computers  (LB 
cluster)  which  Parallels  H-Sphere  regards  and  operates  with  as  a single  server. 

Load  balanced  cluster  solution  in  Parallels  H-Sphere  requires  4 or  more  physical 
servers: 

■ Load  Balancer:  any  solution  like  Cytrix®  NetScaler 
(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314)  for 

balancing  traffic  across  the  web/mail  servers.  Load  Balancer  directs  traffic  to 
another  server  if  the  first  one  is  currently  overloaded.  It  can  also  allow  the  service  to 
continue  even  if  one  of  the  servers  is  down. 

■ One  master  and  one  or  more  slave  servers  form  a load  balanced  Web/mail  cluster. 
All  these  servers  are  being  added  to  Parallels  H-Sphere  as  physical  servers,  with  all 
related  packages  installed,  but  Parallels  H-Sphere  logical  servers  are  created  only 
on  master  servers,  and  Parallels  H-Sphere  operates  with  load  balanced  cluster  only 
via  master  server. 

■ NAS  (Network  Attached  Storage):  shared  storage  for  master  and  slave  servers. 

NAS  is  a highly  reliable  server  with  enough  space  for  storing  data.  Web/mail  content 
directories  are  mounted  to  the  NAS  where  the  content  is  actually  stored.  Web  and 
mail  servers  can  jointly  use  one  NAS  or  have  their  own  NAS  for  Web  and  for  mail. 

Figure  1:  Simple  Load  Balanced  system  with  one  Web  cluster. 
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Figure  2:  More  complex  Load  Balanced  system  with  two  mail  and  two  web  clusters: 


INTERNET 


NAS 

content  storage 

/filer/web_01/h  sphere 
content  storage 
/filer/  web_02/hsphere 
content  storage 
/filer/mail_01/hsphere 
content  storage 
/filer/mail_02/h  sphere 


cluster  mail_02 


Load  Balancing  399 


Load  Balancers 

You  need  to  purchase,  install  and  configure  any  load  balancer  solution,  for  example, 
Cytrix®  NetScaler 

(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314). 

This  task  is  beyond  the  scope  of  Parallels  H-Sphere  documentation. 


Supported  NAS 


The  following  file  storage  systems  (on  page  415)  are  supported  by  Parallels  H-Sphere: 


NAS 

Notation 

Supported  in  Parallels  H-Sphere 

Generic  Linux  NFS  (on  page 
406) 

UNIX 

3.0  RC  1 and  up 

RedHat  GFS  (on  page  406) 

UNIX 

3.0  RC  4 and  up 

NetApp 

(http://www.netapb.com/prod 

ucts/filer/) 

NET  APP 

2.3  and  up  to  2.5 

3.0  RC  1 and  up 

BlueArc 

(http://www.bluearc.com/) 

BLUE  ARC 

2.4.3  Patch  10  and  up 

2.5  Beta  5 and  up 

EMC  Celerra 

(httD://www.emc.com/product 

s/networkina/servers/index.is 

B) 

EMC  CELERRA 

2.4.3  Patch  10  and  up 

2.5  Beta  5 and  up 

Note:  All  Parallels  H-Sphere  customers  will  be  recommended  to  choose  shared  Linux 
NFS  as  the  most  simple  and  reliable  solution. 


Load  Balanced  Cluster 

Loab  balanced  cluster  consists  of  one  master  and  one  or  more  slave  servers  regarded 
by  Parallels  H-Sphere  as  a single  server. 

■ Master  and  slave  servers  are  added  to  Parallels  H-Sphere  as  physical  servers. 

■ Master-slave  relations  between  these  servers  are  set  in  admin  CP. 

■ Only  master  server  is  added  as  Web/mail  logical  server  to  Parallels  H-Sphere.  CP 
communicates  only  with  master  server. 
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■ Requests  are  passed  to  external  IPs  routed  by  the  load  balancer.  Load  balancer 
distributes  requests  evenly  across  the  master  and  slave  servers  (internal  IPs 
corresponding  to  external  IP).  For  this  purpose,  NAT  must  be  properly  configured 
on  load  balanced  cluster  servers. 

■ Master  and  slave  server  share  the  same  Parallels  Pi-Sphere  related  directories 
where  all  user  content,  scripts,  and  the  majority  of  Parallels  Pi-Sphere  related 
binaries  are  located.  These  directories  are  actually  stored  on  the  NAS  and  mounted 
from  master  and  slave  servers  via  NFS. 

■ Along  with  shared  storage,  master  and  slave  servers  have  their  own  unique  IP- 
specific  logs  and  configs  which  are  synchronized  by  special  cron  scripts  run  on 
these  servers. 

See  load  balanced  cluster  scheme  with  generic  Linux  NFS  shared  storage  (on  page 

400). 
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Implementation  of  Load  Balanced  Cluster 
in  Parallels  H-Sphere 

This  section  describes  load  balanced  Web/mail  cluster  scheme  for  generic  Linux  NFS 
(on  page  406)  NAS. 
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Load  Balanced  Cluster  in  CP 

■ Master  and  slave  servers  are  added  to  Parallels  H-Sphere  as  physical  servers. 

■ Master-slave  relations  between  these  servers  are  set  in  admin  CP. 

■ Only  master  server  is  added  as  Web/mail  logical  server  to  Parallels  H-Sphere.  CP 
communicates  only  with  master  server. 


Distribution  of  Requests  Across  Load  Balanced  Cluster 

Parallels  H-Sphere  regards  Web  or  mail  load  balanced  cluster  as  a single  server. 
Requests  are  passed  to  external  IPs  routed  by  the  load  balancer.  Load  balancer 
distributes  requests  evenly  across  the  master  and  slave  servers  (internal  IPs 
corresponding  to  external  IP). 

Shared  Content 

Master  and  slave  servers  share  the  same  /hsphere  directory  mounted  by  NFS  to  the 
/filer /<cluster_type>  <cluster_id>/  directory  on  the  NAS  where  load  balanced 
cluster  content  is  actually  stored.  Here,  <cluster_type>  is  mail  or  web,  and  <cluster_id>  is 
cluster  id  - there  may  be  multiple  load  balanced  clusters  mounted  to  the  NAS:  01 , 02, ... 
(See  the  illustration  (on  page  397)  for  2 Web  and  2 mail  clusters.) 

All  user  content,  scripts,  and  the  majority  of  Parallels  H-Sphere  related  binaries  are 
installed  into  the  /hsphere  directory  and  shared  by  master  and  all  slaves. 

Follow  the  Adding  Load  Balanced  Clusters  on  Shared  Linux  NFS  (on  page  406) 
instructions  to  learn  how  to  correctly  mount  the  shared  storage  on  the  NAS  to  the 
master  and  slave  servers. 
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Specific  Master/Slave  Content 

Along  with  the  common  shared  storage,  master  and  slave  servers  have  their  own 
Parallels  H-Sphere  specific  (Apache,  FTP)  and  IP-dependent  (network)  logs  and 
configuration: 

■ Both  master  and  slave  servers  have  unique  Apache  logs  stored  locally  in  the 
/var/iog/hsphere/httpd  directory  instead  of  the  default 

/hsphere/local/var/httpd/ logs  directory. 

■ On  the  master  server,  Apache,  FTP  and  network  configuration  is  located  in  the 
/hsphere  directory  (which  is  a mountpoint  to  the  NAS  and  is  common  for  the  master 
and  the  slave  servers): 

/hsphere /local/ conf ig/httpd/ 

/hsphere /local/ conf ig/ f tpd/ 

/hsphere /local /network/ 

On  slave  servers,  however,  this  data  is  unique  and  is  stored  locally  in  the 

/etc/hsphere  directory: 

/ etc/hsphere/httpd/ 

/ etc/hsphere/ f tpd/ 

/ etc/hsphere /network/ 

Parallels  H-Sphere  updater  running  with  the  hspackages  siaves=web  |maii  I all 
option  creates  the  /etc/hsphere  directory  data  on  slave  servers. 

Synchronization  Between  Master  and  Slave  Servers 

The  special  cron  script  /hsphere/ shared/ scripts/ cron/lb_sync  . sh  runs  each 
minute  on  each  slave  server  to  synchronize  data  on  master  and  slave  servers.  It  parses 
and  synchronizes: 

■ User  Apache/ProFTPd  config  files 

/ etc/hsphere/ [httpd | f tpd] /sites/*. conf,  and 
/ etc/hsphere /network/ ips 

■ the  /etc/passwd,  /etc/shadow,  /etc/group  files. 
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Traffic  Calculation 


User  logs  are  located  in  the  /hsphere/local/home/<USer>/logs/domain  . com/ 

directory.  On  master  server,  log  filenames  look  like: 


{ domain . name } 
referrer  log 
access_log 
error  log 


Slave  servers  write  the  following  logs: 

{ domain . name } SRV-N 
referrer  log  SRV-N 
access  log  SRV-N 
error  log  SRV-N 

where  n is  slave  server  id:  1 , 2, ... 

The  /hsphere/ shared/ scripts/ cron/ cron-rotate  . pi  script  has  been  adapted 
to  calculate  statistics  on  load  balanced  cluster.  It  runs  on  master  and  slave  servers  by 
the  following  scheme: 

■ on  slave  servers  (e.g.,  1 :30am): 

■ synchronizes  logrotate  conf  files  on  master  and  slaves:  It  parses  log  rotate 
COnfigs  in  the  /hsphere /local/ conf  ig/httpd/ logrotate_conf  s/ 
directory  on  the  master  server.  They  point  to  the  user  logs  located  in  the 

/hsphere/local/home/<user>/logs/domain.  com/  directory.  On  master 
server,  log  filenames  look  like: 

{ domain . name } 
referrer  log 
access_log 
error  log 

Slave  servers  write  the  following  logs: 

{ domain . name } -SRV-N 
referrer  log-SRV-N 
access  log-SRV-N 
error  log  SRV-N 

where  N is  slave  server  id:  1, 2,  ...  cron-rotate.pl  merges  data  and  synchronizes 
respective  master  and  slave  logs. 

■ rotates  logs  on  slave  servers 

■ restarts  Apache 

■ on  master  server  (e.g.,  2:00am): 

■ rotates  logs  on  the  master 

■ restarts  Apache 

■ merges  master  and  slave  logs 

■ launches  log  analyzers  (Webalizer,  AWStats,  ModLogAn) 
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Load  Balanced  Cluster  Map 

The  following  two  files  construct  load  balanced  cluster  map.  At  the  moment,  they  need 
to  be  created  manually  on  master  and  slave  servers: 

■ /hsphere/local/config/lb.map  - created  on  the  master  server  and  has  the  following 
format: 

<Master_IP>  \ <Slave1JP>  | . . . | <SlaveN_IP> 

The  lines  of  the  same  format  should  be  also  added  for  each  dedicated  IP  bound  on 
the  cluster: 

<Master_Dedicated_IP>  \ <S!ave1JDedicatedJP>  | . . . | <SlaveN_Dedicated_IP> 

• /etc/hsphere/lb.id  - created  on  both  the  master  and  slave  servers  and  contains  the 
following  line: 

<CLUSTER_TYPE>  \ <SERVER_ID> 

where  <CLUSTER_TYPE>  is  mail  or  web;  <SERVER_ID>  is  LB  server  id:  0 for  master,  1 
for  the  first  slave,  2 for  the  second  slave,  etc. 

For  example,  for  slave  server  with  <Slave2_IP>  in  LB  Web  cluster  the  lb. id  file  will 
look  like: 

web  | 2 
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NAT  Configuration  for  Load  Balanced  Clusters 

To  configure  load  balanced  Web/mail  cluster  with  NAT,  you  must  have  NAT  turned  on 
(on  page  28)  in  Parallels  H-Sphere  and  put  external  Web/mail  server  IP  routed  by  the 
Load  Balancer  into  correspondence  with  the  master  server's  internal  IP. 

For  example,  for  a load  balanced  Web  cluster  with  one  master  and  4 slave  servers, 
where  the  master  Web  server's  internal  IP  192.168.0.100  corresponds  to  the 
external  IP  12.34. 56.100  bound  to  the  Load  Balancer. 

■ In  the  ~cpanel/shiva/psoft_config/ips-map.xml  file  on  the  CP  server  there  should  be 
the  following  record: 

<ips> 

<ip  ext="12 .34.56.100"  int="192 . 168 . 0 . 100"/> 

</ ips> 

■ All  dedicated  IPs  on  the  master  server  must  be  also  associated  with  corresponding 
IPs  on  the  Load  Balancer  and  similar  records  must  be  added  to  the  ip-map.xml  file: 

<ip  ext="LB  Dedicated  IP"  int="Master  Dedicated  IP"/> 

■ Also,  you  should  have  external  IP  in  the  E. Manager  ->  DNS  Manager  ->  Service  Zone 
menu  in  admin  CP.  For  example: 

www.test.com  3600  IN  A 12.34.56.100 
mail.test.com  3600  IN  MX  12.34.56.111 
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Load  Balancing  Support  in  Parallels  H- 
Sphere 

This  document  explains  functionality  of  the  scripts  that  enable  distribution  of  load 

balance  between  Apache  and  Virtual  FTP  servers. 

■ apache-confsynch.pl  accounts  for  synchronization  of  Apache  config  files  on  slave 
servers.  Amount  of  slave  servers  and  their  IDs  are  set  at  master  server  in  the 

/hsphere/local/ config/ slaves  . conf  file.  The  script,  also,  creates 
need_restart.txt  on  each  slave  to  mark  it  as  liable  to  restart. 

■ apache-need-restart.pl  runs  on  slave  servers,  checks  if  need_restart.txt  is 
available  there  and  marks  them  as  liable  to  restart.  In  other  words  this  script  servers 
as  a layer  between  LB  apache  restart  and  standard  apache-restart. 

■ apache-reconfig.pl  is  a modification  of  a standard  apache-reconfig  script/file(?) 
that  is  executed  on  slaves  and  is  only  different  from  it  in  that  it  sets  required  level  of 
restart  for  slaves  (either  gracefull  or  force). 

■ apache-repair.pl  is  a modification  of  a standard  apache-repair.pl  script  and  is  only 
different  in  that  it  sets  exclusive  lock  for  /etc/passwd,  /etc/shadow, 
/etc/groups  so  to  ensure  these  files  are  not  locked  by  rsync  and  so  a user  can 
be  started.  Otherwise,  all  files  will  be  marked  as  bad. 

■ ftp_anlz.pl  gathers  and  analyses  statistics 

■ ftp_anlz_user.pl  gathers  and  analyses  user  statistics. 

■ ftp-confsynch.pl  accounts  for  the  same  as  apache-confsynch.pl  on  Virtual  FTP 
severs. 

■ ftp-need-restart.pl  accounts  for  the  same  as  apache-need-restart.pl  on  Virtual  FTP 
severs. 

■ ftp-restart.pl  is  the  same  as  Apache,  but  for  Virtual  FTP 

■ master-ipsynch.pl  runs  on  a master  server  and  formats  data  for  slave  servers  so 
IPs  are  up  according  to  IP  mapping  set  in  the 

/hsphere/local/ conf  ig/map_table  . txt  file  on  each  slave. 

■ slave-ipupdate.pl  puts  up  IPs  formed  by  the  master-ipsynch . pi  script. 

As  of  now  Apache  and  Virtual  FTP  config  files  synchronization  is  executed  on  master 

server,  yet  it  is  expected  to  be  moved  onto  slave  servers. 


Load  Balancing  407 


Installing  Load  Balanced  Web/Mail 
Clusters  in  Parallels  H-Sphere 

Load  balanced  cluster  solution  requires  3 or  more  physical  servers: 

■ Load  Balancer:  any  solution  like  Cytrix®  NetScaler 
(http://www.citrix.com/Enqlish/ps2/products/subfeature.asp?contentlD=22314)  for 

load  balancing  across  the  web/mail  servers.  Load  Balancer  directs  traffic  to  another 
server  if  the  first  one  is  currently  overloaded. 

■ NAS  (aka  Filer):  Server/client  shared  storage  solution  for  web/mail  content.  NAS 
may  be  installed  on  the  same  server  with  load  balancer  or  on  a separate  server. 
Also,  Web  and  mail  servers  can  jointly  use  one  NAS  or  have  their  own  NAS  one  for 
Web  and  one  for  mail.  In  this  documentation  we  consider  the  following  NAS's: 

■ Generic  Linux  NFS 

■ NetApp  Filer  hardware 
- RedHat  GFS 

■ At  least  two  boxes  (master  and  slave)  for  web/mail  servers.  Load  balanced 
solution  implies  one  master  server  and  one  or  more  slave  servers. 

> To  create  Web/mail  load  balanced  clusters  integrated  into  Parallels  H-Sphere: 

1 Install  and  configure  Load  Balancer  (on  page  407) 

2 Prepare  NAS  (on  page  408) 

3 Prepare  master  and  slave  Web/mail  boxes  (on  page  412) 

4 Install  Parallels  Fl-Sphere  to  load  balanced  Web/mail  clusters  (on 
page  41 4) 


In  this  section: 


Step  1.  Install  and  Configure  Load  Balancer 407 

Step  2.  Prepare  NAS 408 

Step  3.  Prepare  Master  and  Slave  Web/Mail  Boxes 412 


Step  4.  Install  Parallels  Fl-Sphere  to  Load  Balanced  Parallels  Fl-Sphere  Clusters  414 
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Step  1 . Install  and  Configure  Load  Balancer 

Purchase,  install  and  configure  load  balancer  solution  like  Cytrix®  NetScaler. 

Step  2.  Prepare  NAS 

Follow  procedures  below  for: 

■ NetApp  hardware  (on  page  406) 

■ Linux  NFS  shared  storage  (on  page  406) 

■ RedHat  GFS  (on  page  406) 


In  this  section: 


NetApp  Fiardware 408 

Generic  Linux  NFS 409 

RedFiat  GFS 411 


NetApp  Hardware 

1 Purchase  NetApp  NAS  from  www.netapp.com,  install  and  configure 
the  NAS  according  to  the  NetApp  Documentation 
(http://www.netapp.com/products/filer/).  Create  volumes/qtrees  on  the 
box  where  NetApp  NAS  is  to  be  installed. 

2 Configure  your  NetApp  NAS  to  add  load  balanced  cluster  in  Parallels 
H-Sphere  (read  the  NetApp  Manual  at 

http://ecserv1  .uwaterloo.ca/netapp/man/  for  commands): 

1.  Telnet  to  the  NetApp  NAS: 
telnet  <NAS_IP> 

Flere,  <NAS_IP>  is  the  NetApp  NAS  IP. 

2.  Get  the  list  of  the  NAS  partitions  with  the  qtree  command: 

# qtree 

3.  To  enable  disk  quota  management,  export  the  /etc  directory  on  the  NetApp  NAS 
and  allow  to  mount  it  only  from  the  CP  box: 

# exportfs  -o  access=<CP_IP>,root=<CP_IP>,rw=<CP_IP>  /etc 

Here,  <CP_IP>  is  the  CP  server  IP. 

4.  To  enable  user  disk  space  management  on  the  web/mail  servers,  export  the 
user  storage  directory  on  the  NetApp  NAS  allow  to  mount  it  from  the  physical 
web/mail  boxes: 
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# exportfs  -o 

access=<Master_IP> : <Slavel_IP> [ :<Slave2_IP>: . . . ] , root=<Master_ 

IP> :<Slavel_IP> [ : . . .] ,rw=<Master_IP>:<Slavel_IP>[ : . . .] 

<NAS_WebPath> 

Here,  <Master_IP> : <Slave1JP>  [ : <Slave2_IP> : . . . ] is  the  list  of  master  and  slave 
web/mail  server  IPs  separated  with  colon  (:),  <NAS_WebPath>  is  the  user  storage 
directory. 

5.  Exit  telnet  session  on  the  NetApp  NAS. 

3 Prepare  NetApp  NAS  to  Work  With  Parallels  H-Sphere 

1 . Grant  rsh  access  to  the  NetApp  NAS  from  the  CP  box  to  root  and  cpanel  user. 

2.  Grant  nfs  access  to  the  /etc  directory  for  the  CP  box  in  rw  mode. 

3.  Grant  nfs  access  to  the  home  directory  on  the  storage  partition  (e.g., 
/vol/volO/home)  for  the  CP  box  in  rw  mode  with  root  privileges  (e.g.,  - 
access=1 92.1 68.0.9:1 92.1 68.0.1 0,  root=1 92.1 68.0.8:1 92.1 68.0.9:1 92.1 68.0.1 0). 

4.  On  CP  server,  set  the  QUOTA_MANAGER  property  in 
~cpanel/shiva/psoft_config/hsphere. properties  to  support  NetApp  quota 
manager  on  LB  cluster: 

QUOTA_MANAGER  = NET_APP 

More  about  external  quota  manager  support  in  Parallels  H-Sphere  (on  page  415). 
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Important:  For  correct  load  balanced  cluster  implementation,  NFS  must  be  of  version 
3. 

1 Login  as  root  to  a new  Linux  server  assigned  for  NAS  and  create  a 
separate  partition  for  shared  file  storage.  This  partition  must  be  on  a 
separate  hard  drive  on  a separate  controller  and  must  not  be  /var  or 
/usr.  We  recommend  naming  it  /filer  to  avoid  possible  confusion. 

2 Install/update  the  quota-3  . x package  from  the  following  location: 

# rpm  -Uvh 

http : / / download . hsphere .parallels . com/ shiv/HS/<OSCQDE>/ sysutil 

s/quota-3 .xx-x . i386 . rpm 

where  <OSCODE>  is  a mnemonic  code  for  operating  system  supported  by  Parallels 
H-Sphere  (see  OSCODE  notation  in  Appendix  D of  Parallels  H-Sphere  Update 
Guide). 

Important:  The  quota  package  includes  NFS  support,  which  is  essential  for  load 
balanced  cluster  implementation.  Generic  quota  package  has  NFS  support  disabled 
by  default! 

3 Add  the  "usrquota"  option  to  the  /filer  partition  in  /etc/fstab: 
LABEL=/filer  /filer  ext3  defaults , usrquota  1 1 

To  apply  changes,  run: 

# mount  -o  remount  /filer 

# quotacheck  -m  /filer 
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# quotaon  /filer 

4 On  the  /filer  partition,  create  directories  for  load  balanced  cluster 
file  storage: 

# mkdir  -p  /filer/ <CLUSTER_TYPE>_<CLUSTERJD> /hsphere 

where  <CLUSTER_TYPE>  is  web  or  mail,  and  <CLUSTER_ID>  is  a cluster  id  (there  may 
be  multiple  clusters  mounted  to  the  same  NAS). 

For  example,  for  the  first  Web  cluster  it  will  be  /f  iier/web_Ol/hsphere. 

5 Stop  all  services  except  ssh,  portmap,  and  nfs  related  services.  Check 
the  status  by  the  chkconfig  command: 

# chkconfig  --list 

6 To  enable  user  disk  space  management  on  the  web/mail  servers, 
export  the  user  storage  directory  on  the  generic  Linux  NAS.  For  this, 
add  the  following  lines  for  all  clusters  to  the  /etc/exports  file  on 
the  NAS  server: 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Master  IP> (rw, async, no  wdelay, insecure , no  root  squash) 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Slavel  IP> (rw, async, no  wdelay, insecure , no  root  squash) 

/ filer/ <CLUSTER_TYPE>_<CLUSTER_ID>/hsphere 

<Slave2  IP> (rw, async, no  wdelay, insecure , no  root  squash) 

To  apply  changes,  run: 

# exportfs  -a 

7 Skip  this  step  for  mail  server  clusters. 

Edit  the  /etc/init . d/nf  s file.  Find  the  line  with  daemon  rpc.  rquotad  and  add 
the  -S  option  to  the  end  of  the  line,  like  this: 

daemon  rpc. rquotad  $RPCRQUOTADOPTS  -S 

After  that,  restart  NFS: 

# chkconfig  --level  345  nfs  on 

# /etc/init .d/nf s restart 

Important:  NFS  configuration  on  the  NAS  may  differ  depending  on  the  hardware 
parameters,  the  number  of  clusters,  quota  and  load  on  the  servers.  To  properly 
configure  NAS  please  refer  to  the  following  guides: 


https://www.redhat.eom/f/pdf/rhel4/NFSv4WP.pdf 

http://www.citi.umich.edu/proiects/nfs-perf/results/cel/dnlc.html 

http://www.oreillv.com/cataloq/nfs2/chapter/ch15.html 
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RedHat  GFS 

> To  prepare  NAS  for  RedHat  GFS  filer  (http://www.redhat.com/software/rha/pfs/): 

1 Install  and  configure  RedHat  GFS  cluster  on  a filer  according  to  the 
following  documentation: 

http://www.redhat.com/docs/manuals/csafs/browse/rh-gfs-en/index.html 

http://www.redhat.com/docs/manuals/csqfs/browse/rh-cs-en/index.html 

http://www.tldp.org/HOWTO/LVM-HOWTO/index.html 

2 Setup  GFS  file  system  type  on  a logical  volume  on  the  filer,  like  this: 

# gfs_mkfs  -p  lock_type  -t  cluster_name : gnbd_device  -j  2 
/ dev/ vg_name/ lv_name 

where  iock_type  is  a GFS  locking  type,  ciuster_name  is  a GFS  cluster  name, 
gnbd_device  is  a GNBD  device  name,  vg_name  is  a volume  group  name,  and 
iv_name  is  a logical  volume  name.  Further  on  in  the  document  we  will  use  the 
following  example: 

# gfs_mkfs  -p  lock_dlm  -t  alpha_cluster : gf si  -j  2 
/dev/vgOl/lvOl 

3 Start  GNBD  server: 

# gnbd_serv 

Upon  successful  start,  you'll  get  the  following  output: 

gnbd_serv:  startup  succeeded 

4 Export  logical  volume  with  GFS  file  system: 

# gnbd_export  -d  /dev/vgOl/lvOl  -e  gfsl 
You  should  get  the  following  output: 

gnbd  clusterd:  connected 

gnbd  export:  created  GNBD  gfsl  serving  file  /dev/vgOl/lvOl 
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Step  3.  Prepare  Master  and  Slave  Web/Mail  Boxes 

Before  you  install  Parallels  H-Sphere  packages  to  master  and  slave  servers,  please 
make  sure  to  meet  the  following  requirements  for  correct  load  balancing: 

■ All  boxes  in  LB  cluster  must  have  the  same  OS  version  installed  on.  For  RedPlat 
GFS,  all  servers  must  be  RedFlat  servers.  In  case  of  generic  Linux  NFS  or  NetApp, 
master/slave  servers  under  FreeBSD  are  supported  in  FIS  3.0  RC  4 and  up. 

■ The  /hsphere  directory  on  a Web  server  should  not  be  created  a separate 
partition! 

The  operations  on  master  and  slave  servers  are  made  under  root. 

1 Create  the  /hsphere  directory  on  the  master  and  all  slave  servers: 

# mkdir  /hsphere 

2 If  you  are  using  GFS,  run  on  each  master  and  slave  servers: 

1.  Load  kernel  module: 

# modprobe  gnbd 

2.  Import  GFS  file  system  from  the  NAS  server: 

# gnbd_import  -i  FILER_NAME 

where  filer_name  is  the  NAS  server  domain  name.  You  should  get  the 
following  output: 

gnbd  import:  created  gnbd  device  gfsl 

gnbd  monitor:  gnbd  monitor  started.  Monitoring  device  #0 
gnbd  recvd:  gnbd  recvd  started 

3 Mount  the  storage  directory  on  the  NAS  server  to  /hsphere  directory 
on  the  master  and  all  slave  servers. 

a For  RedHat  GFS: 

Add  the  following  mountpoint  to  /etc/fstab  on  the  master  and  all  slave  servers: 
/dev/gnbd/gf si  /hsphere  gfs  defaults  0 0 

Mount  the  GFS  logical  volume  on  the  master  and  all  slave  servers: 

# mount  -t  gfs  /dev/gnbd/gf si  /hsphere 

b For  generic  Linux  NFS  or  NetApp: 

Add  the  following  mountpoint  to  /etc/fstab  on  the  master  and  all  slave 
servers: 

<NASJP> : / filer /<CLUSTERTYPE>  <CLUSTERJD> /hsphe  re  /hsphere  nfs 
defaults , nfsvers=3 , rsize=327 68 , wsize=327 68  0 0 

For  mail  server  cluster,  also  add  these  mountpoints  on  all  servers: 

<NASJP>  : / filer/ <CLUSTER_TYPE>  <CLUSTER_ID>/ users  / var/ qmail/users 
nfs  defaults , nfsvers=3  0 0 

<NASJP> : / filer /<CLUSTER_TYPE>  <CLUSTER_ID>  / control 
/var/qmail/control  nfs  defaults , nfsvers=3  0 0 

To  mount  the  directory,  run: 
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# mount  -a  &&  mount 

4 On  the  master  server,  create  the 

/hsphere/local/config/lb. map  file  of  the  following  format: 

<Master_IP>  \ <Slave1JP>  | . . . | <SlaveN_IP> 


Note:  The  lines  of  the  same  format  should  be  also  added  for  each  dedicated  IP 
bound  on  the  cluster: 

<Master_Dedicated_IP> \<Slave1_Dedicated_IP>  \ . . .\<SlaveN_Dedicated_IP> 

5 On  every  master  and  slave  server,  create  the 
/etc/hsphere/ lb . id  file  with  the  line  of  the  following  format: 

<CLUSTER_TYPE>  \ <SERVER_ID> 

where  <CLUSTER_TYPE>  is  mail  or  web;  <SERVER_ID>  is  LB  server  id:  0 for  master,  1 
for  the  first  slave,  2 for  the  second  slave,  etc. 

For  example,  for  slave  server  with  <Slave2_IP>  in  LB  Web  cluster  the  lb. id  file  will 
look  like: 

web  | 2 

6 Generate  SSH  keys  to  access  the  master's  root  from  each  slave 
server  without  password. 

1 . Log  into  each  slave  server  as  root. 

2.  Create  public  key  on  each  slave  server: 

# ssh-keygen  -t  dsa 

3.  Log  from  each  slave  server  to  the  master  server  as  root  and  insert  the  contents 
of  the  /root/ . ssh/ id_dsa . pub  file  from  each  slave  server  into  the 

/root/ . ssh/authorized  keys2  file  of  the  master  server. 

4.  Log  from  the  each  slave  server  into  the  master  server  as  root  once  again  to 
ensure  slave  servers  are  able  to  log  into  the  master  without  password: 

# ssh  root@<Master_IP> 

Answer  yes  to  all  prompts.  This  will  add  the  master  server  to  the  list  of  known 
hosts  (/root/ . ssh/known_hosts)  of  a slave  server.  After  that,  load 
balancing  synchronization  scripts  will  work  without  password  prompts. 

7 Important:  To  make  sure  Parallels  H-Sphere  related  data  is  correctly 
synchronized  on  master  and  slave  servers,  add  time  synchronization 
(on  page  32)  to  the  master  and  slave  servers'  crontabs. 
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Step  4.  Install  Parallels  H-Sphere  to  Load  Balanced 
Parallels  H-Sphere  Clusters 

1 Log  into  Parallels  H-Sphere  admin  CP  (it  is  assumed  you  have 
Parallels  H-Sphere  3.0  and  up  already  installed). 

2 Add  master  and  all  slave  servers  as  physical  servers  to  Parallels  H- 
Sphere. 

3 Set  master-slave  relations  between  master  and  slave  physical 
servers.  This  is  described  in  the  section  Load  Balanced  Server 
Clusters  of  Parallels  H-Sphere  Service  Administrator  Guide. 

4 Add  Web/mail  logical  server  only  to  master  physical  server.  Do  not 

add  logical  servers  to  slave  servers! 

In  logical  server  options  you  need  to  set  Load  Balancer  Server  Parameters: 

■ File  Server  Type:  file  storage  OS  type  (on  page  397),  like  UNIX  for  generic 
Linux  NFS 

■ File  Server:  file  storage  volume  location,  like 

<NASJP>:  / £ Her /<CLUSTER  TYPE>  <CLUSTER  ID> / in  the  above  example 

■ File  Path:  (optional)  file  storage  path  to  Parallels  H-Sphere  installation  directory, 
like  / filer /<CLUSTER_TYPE>  <CLUSTER_ID> /hsphere  in  the  above  example 

■ File  server  Volume  ID:  file  storage  volume  ID,  like 
<CLUSTER_TYPE>  <CLUSTER_ID>  in  the  above  example. 

5 For  mail  LB  cluster,  it  is  required  to  configure  Horde  Webmail  frontend 
(on  page  155)  to  use  external  Web  server  and  external  MySQL 
database  server,  and  also  to  configure  SpamAssassin  (on  page  180) 
to  external  MySQL  database. 

6 Configure  NAT  for  LB  Web/mail  clusters 

Parallels  H-Sphere  Control  Panel  works  with  only  one  logical  server  (that  is,  master 
server)  for  each  load  balanced  Web  cluster.  To  configure  load  balanced  Web/mail 
cluster  with  NAT,  you  must  have  NAT  turned  on  (on  page  28)  in  Parallels  H-Sphere 
and  put  external  Web/mail  server  IP  routed  by  the  Load  Balancer  into 
correspondence  with  the  master  server's  internal  IP. 

For  example,  for  a load  balanced  Web  cluster  with  one  master  and  4 slave  servers, 
where  the  master  Web  server's  internal  IP  192.168.0.100  corresponds  to  the 
external  IP  12. 34. 56.100  bound  to  the  Load  Balancer. 

■ In  the  ~cpanei/shiva/psoft  config/ips-map . xml  file  on  the  CP  server 
there  should  be  the  following  record: 

<ips> 

<ip  ext="12 .34.56.100"  int="192 . 168 . 0 . 100"/> 

</ ips> 
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■ All  dedicated  IPs  on  the  master  server  must  be  also  associated  with 
corresponding  IPs  on  the  Load  Balancer  and  similar  records  must  be  added  to 
the  ip-map. xml  file: 

<ip  ext="LB  Dedicated  IP"  int="Master  Dedicated  IP"/> 

■ Also,  you  should  have  external  IP  in  the  E. Manager  ->  DNS  Manager  ->  Service  Zone 
menu  in  admin  CP.  For  example: 

www.test.com  3600  IN  A 12.34.56.100 
mail.test.com  3600  IN  MX  12.34.56.111 

7 Download  the  latest  Parallels  H-Sphere  updater  of  Parallels  H-Sphere 
3.0  RC  1 and  up  and  follow  the  instructions  on  adding  new  servers 
into  Parallels  H-Sphere  to  install  Parallels  H-Sphere  related  packages 

only  on  master  server. 

8 In  the  updater's  command  line,  run  one  of  the  following  commands  to 
complete  installation  and  configuration  on  slave  servers: 

hspackages  slaves=web 
hspackages  slaves=mail 
hspackages  slaves=all 

More  about  updater  options  read  in  Parallels  H-Sphere  Update  Guide. 


Quota  Managers 

Parallels  H-Sphere  supports  quota  management  for  third  party  file  storage  systems  like 
BlueArc  or  NetApp  for  load  balanced  Web/mail  clusters  (on  page  397).  If  not  specified 
otherwise,  Parallels  H-Sphere  uses  generic  Linux/FreeBSD  server  quota  manager. 

To  set  a third  party  NAS  quota  manager,  add  the  quota_manager  variable  in 

~cpanel/ shiva /pso ft  config/h sphere  .properties,  for  example,  like  this: 

QUOTA_MANAGER  = BLUE_ARC 

The  following  quota  managers  are  supported: 

■ UNIX  - generic  Linux/FreeBSD  quota  manager  (default) 

■ NET_APP  - NetApp  quota  manager  (http://www.netapp.com/products/filer/) 

■ BLUE_ARC  - BlueArc  quota  manager  (http://www.bluearc.com/) 

■ EMC_CELERRA  - EMC  Celerra  quota  manager 
(http://www.emc.com/products/networkinq/servers/index.isp) 
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This  chapter  explains  how  to  migrate  resources  into  Parallels  H-Sphere  from  Parallels 
H-Sphere  and  other  control  panels  using  XML-structured  data.  It  can  also  serve  as  a 
guide  to  setting  up  a large  number  of  Parallels  H-  Sphere  users  at  a time.  You  are 
expected  to  have  an  installed  and  configured  Parallels  H-Sphere  control  panel  on  the 
target  server. 

Migratable  Resources 

Users  can  be  migrated  with  the  following  resources: 

■ User  contact  and  billing  info 

■ Domains  (with  or  without  DNS) 

■ DNS:  custom  A,  MX,  CNAME  records;  domain  vhost  aliases;  domain  aliases  with 
their  DNS  and  mail  configuration 

■ Web:  settings,  FrontPage,  CGI,  CGIDir,  MIME,  PHP,  SSI,  ErrorDoc,  ErrorLog, 
TransferLog,  Webalizer,  ModLogAn,  RefferrerLog,  AgentLog,  Vhost  alias,  Directory 
indexes,  Redirect,  Urchin3,  Urchin4,  ASP,  ASP.NET,  ColdFusion,  MSSQLManager 

■ Mail:  Mailboxes,  Autoresponder  for  mailboxes,  Mailforwards,  Mailing  lists 

■ FTP:  resources:  virtual  hosts,  anonymous  virtual  hosts,  virtual  host  directories  with 
permissions,  virtual  host  users,  FTP  subaccounts  (Unix) 

■ MySQL:  users,  databases  with  user  permissions 

■ PostgreSQL:  users,  databases 

■ MSSQL:  users,  logins,  databases 

■ ODBC:  dsn  records  with  params 

Crontab:  crontab  records  for  users  The  following  resources  are  NOT  YET  implemented 
in  XML  migration  mechanism: 

■ DNS:  instant  access  domain  alias 

■ Web:  SSL,  Shared  SSL,  MivaEmpresa,  MivaCart,  osCommerce,  PhpBB 


In  this  chapter: 

Migration  Procedure 
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Migration  Procedure 

The  migration  procedure  takes  the  steps  below. 


In  this  section: 


Step  1.  Create  XML  File  Containing  User  Data 417 

Step  2.  Create  XML  File  Containing  Reseller  Plan  Data 423 

Step  3.  Prepare  The  Target  Control  Panel 429 

Step  4.  Create  Reseller  Plans 429 

Step  5.  Create  Resellers 429 

Step  6.  Create  End  Users 430 

Troubleshooting 430 


Step  1 . Create  XML  File  Containing  User  Data 

Create  xml  and  dtd  files  to  migrate  resellers  and  end  users  or  end  users  without 
resellers. 

If  you  are  moving  users  from  Parallels  H-Sphere,  do  it  with  the  UserlnfoExtractor  utility 
as  suggested  in  Creating  User  Migration  XMLs  in  Parallels  Pi-Sphere  (on  page  418). 

If  you  are  moving  users  from  a different  control  panel,  follow  the  instruction  on  Creating 
User  Migration  XMLs  Outside  Parallels  Pi-Sphere  (on  page  422). 

In  this  section: 


Creating  User  Migration  XMLs  in  Parallels  H-Sphere 418 

Creating  User  Migration  XMLs  Outside  Parallels  Pi-Sphere 422 
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Creating  User  Migration  XMLs  in  Parallels  H-Sphere 

This  document  explains  how  to  create  XML  files  with  Parallels  H-Sphere  reseller  and 
end  user  data  for  migration  to  a different  Parallels  H-Sphere  cluster. 

User  info  can  be  obtained  and  formatted  with  the  UsersinfoExtractor  utility 
executed  under  Control  Panel  user  (on  page  65). 

UsersinfoExtractor  extracts  resellers  into  the  migrate  resellers  . xml,  and 

their  end  users  separately  into  migrate_users  .xml. 

UsersinfoExtractor  runs  with  the  following  parameters: 

■ -resellers  - extracts  only  resellers  into  the  migrate_resellers.xml  file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  OPTIONS 

where  options  include: 

■ -reseiiersbynames  - extract  listed  resellers: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -reseiiersbynames  <RESELLER-1>  . . . <RESELLER-N> 

• -reseiiersf  romf  ile  - extract  resellers  listed  in  a plain  text  file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -reseiiersf romf ile  /home/resellers . txt 

■ -usersbynames  - extract  resellers  for  listed  individual  users: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersbynames  <USERNAME-1>  . . . <USERNAME-N> 

• -usersfromfile  - extract  resellers  for  individual  users  listed  in  a plain  text  file: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersfromfile  /home/users . txt 

■ -use rsbyl server  - extract  resellers  for  all  users  located  on  a specified  logical 
server: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  - 
resellers  -usersbylserver  <LSERVER_ID> 

■ -users  - extracts  end  users  into  the  migrate_users . xml  file.  This  option  is 
meant  by  default  if  both  -resellers  and  -users  options  are  omitted  in  the 
command: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  [- 
users]  OPTIONS 

where  options  include: 

■ -usersbynames  - extract  listed  end  users  by  usernames: 

java  psoft.hsphere. migrator .UsersinfoExtractor  [-force]  -users 
-usersbynames  <USERNAME-1>  . . . <USERNAME-N> 

■ -usersfromfile  - extract  users  by  usernames  listed  in  a plain  text  file: 
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java  psof t.hsphere. migrator . UsersInfoExtractor  [-force]  -users 
-usersf romf ile  /home/users . txt 

■ -reseiiersbynames  - extract  users  that  belong  to  listed  resellers: 

java  psof t.hsphere. migrator .UsersInfoExtractor  [-force]  -users 
-reseiiersbynames  <RESELLER-1>  . . . <RESELLER-N> 

■ -reseiiersf  romf  ile  - extract  users  that  belong  to  resellers  listed  in  a plain 
text  file: 

java  psof t.hsphere. migrator .UsersInfoExtractor  [-force]  -users 
-reseiiersf romf ile  /home/ resellers . txt 

■ -use rsbyl server  - extract  users  located  on  a certain  logical  server: 

java  psof t.hsphere. migrator .UsersInfoExtractor  [-force]  -users 
-usersbylserver  <LSERVER_ID> 


Use  the  force  parameter  to  ignore  errors.  Error  messages  will  be  written  to 

migrate  errors.log. 


Important:  Note  that  you  must  specify  user  and  reseller  names,  not  ids! 

Important:  If  you  are  migrating  master  admin's  end  users,  you  just  extract  them  into 
migrate_users . xml  without  extracting  master  admin  as  reseller. 


See  also: 

■ Sample  xml  file  with  reseller  data: 

http://hsDhere.parallels.com/HSdocumentation/xmls/migrate  resellers  25.xml 

■ Sample  xml  file  with  end  user  data: 
http://hsphere.parallels.com/HSdocumentation/xmls/migrate  users  25.xml 

■ Sample  dtd  file  for  resellers: 

http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd 

■ Explanations  to  dtd  file  for  resellers  (on  page  420) 

■ Sample  dtd  file  for  end  users: 
http://hsphere.parallels.com/HSdocumentation/xmls/users.dtd 

■ Explanations  to  dtd  file  for  end  users: 
http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ 

In  this  section: 


DTD  Structure  of  Reseller  XML  Migration  File 
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DTD  Structure  of  Reseller  XML  Migration  File 


Data  Type  Definitions 

Here  is  the  DTD  structure  defined  in  resellers. dtd: 

<?xml  version="l . 0"  encoding="UTF-8"?> 

<!ELEMENT  resellers  (reseller*,  users?) > 

<!ELEMENT  reseller  (info+, administrator, zone*, users?) > 
<!ELEMENT  zone  ( instantalias* ) > 

<! ELEMENT  instantalias  (#PCDATA)> 

<! ELEMENT  administrator  (#PCDATA)> 

< ! ATTLIST  reseller  login  CDATA  #REQUIRED> 

< ! ATTLIST  reseller  password  CDATA  #REQUIRED> 

<! ATTLIST  reseller  plan  CDATA  #REQUIRED> 

<! ATTLIST  administrator  login  CDATA  #REQUIRED> 

<! ATTLIST  administrator  password  CDATA  #REQUIRED> 

<! ATTLIST  administrator  email  CDATA  #REQUIRED> 

<! ATTLIST  zone  name  CDATA  #REQUIRED> 

<! ATTLIST  zone  email  CDATA  #REQUIRED> 

<! ATTLIST  instantalias  prefix  CDATA  #REQUIRED> 

<! ATTLIST  instantalias  tag  CDATA  #REQUIRED> 

<!ENTITY  % users  rules  SYSTEM  "users. dtd">  %users  rules; 


DTD  Chart 

The  above  structure  may  be  represented  graphically  in  the  following  chart: 

resellers 

/ ... 

reseller 

/I 

/ 

/ / \ 

/ / \ 

info  / \ 

administrator  zone 

item  instantalias 


Attributes  Description 

■ reseller: 

■ login  - reseller  login 

■ password  - reseller  password 

■ plan  - the  plan  the  reseller  is  signed  up  for 
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■ info  (contact/billing  signup  information):  (see  signup  fields  description  in  the  section 
User  Signup  Customization  of  Parallels  H-Sphere  Customization  Guide) 

■ type="_ci_"  (contact  info)  or  type="_bi_"  (billing  info) 

■ administrator: 

■ login  - reseller  admin  cp  login 

■ password  - reseller  admin  cp  password 

■ email  - reseller  admin  email  address 

■ zone: 

■ name  - the  name  of  the  reseller  service  zone 

■ email  - email  for  the  reseller  service  zone  (for  example,  if  it  is 
reseller@example.com,  it  must  be  set  as  reseller . example . com) 

■ instantalias: 

■ prefix  - prefix  to  be  added  to  instant  aliases  for  this  zone  (for  example,  u) 

■ tag  - shared  IP  tag  for  the  instant  alias  (usually,  2) 

XML  example  with  reseller  data: 

http://hsphere.parallels.com/HSdocumentation/xmls/migrate  resellers  25.xml 


422 


Resources  Migration 


Creating  User  Migration  XMLs  Outside  Parallels  H-Sphere 

This  section  explains  how  to  format  user  data  for  migration  from  third  party  hosting 
systems  into  Parallels  H-Sphere.  Use  it  to: 

■ migrate  direct  end  users,  resellers,  and  resellers'  end  users; 

■ migrate  only  direct  end  users  if  you  don't  have  resellers. 


Files 

Create  the  following  files: 

■ resellers.dtd  - data  type  definitions  for  resellers 

■ example:  http://hsphere.parallels.com/HSdocumentation/xmls/resellers.dtd 

■ explanation  (on  page  420) 

■ users.dtd  - data  type  definitions  for  end  users 

■ example:  http://hsphere.parallels.com/HSdocumentation/xmls/users.dtd 

■ explanation:  http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ 

■ migrate_resellers.xml  - XML  file  containing  reseller  data  only 

■ example: 

http://hsphere.parallels.com/HSdocumentation/xmls/migrate  resellers  25.xml 

■ explanation  (on  page  420) 

■ migrate_users.xml  - XML  file  containing  user  data  only 

■ example: 

http://hsphere.parallels.com/HSdocumentation/xmls/miqrate  users  25.xml 

■ explanation:  http://hsphere.parallels.com/HSdocumentation/xmls/userxml/ 
You  may  have  data  for  hundreds  and  thousands  of  users  in  the  xml  file. 

Alternatively,  you  may  set  DTD  definitions  directly  within  the  XML  file: 

<?xml  version="l . 0"  encoding="utf-8"?> 

< ! DOCTYPE  users  [ 

//  DTD  rules  as  in  users.dtd 

]> 

<users> 


We  recommend  defining  DTD  externally,  using  our  latest  DTD: 

<! DOCTYPE  users  SYSTEM  "users. dtd"> 

<! DOCTYPE  resellers  SYSTEM  "resellers . dtd"> 

DTD  files  help  ensure  that  all  XMLs  are  formatted  the  right  way.  But  please  note  that 
XML  files  will  be  created  no  matter  DTD  file  exists  or  not. 


Warning:  If  you  make  a mistake  in  DTD  definitions,  migration  may  fail. 
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XML  Validation 

Once  you  have  created  the  XML,  please  do  the  following: 

1 Validate  the  user  data  xml  files  with  any  xml  validation  software. 

2 Make  sure  the  xml  file  does  not  contain  user  with  the  login  "admin". 

3 Make  sure  that  mail  sections  of  each  user  don't  contain  mail  loops. 

4 Ensure  that  the  billing  period  starting  date  has  the  MM/DD/YY  format. 

5 Make  sure  that  in  the  user  tag  the  value  of  the  login  attribute  is  unique  and  doesn't 
begin  with  a number  (this  value  will  be  used  as  the  Parallels  H-Sphere  control  panel 
login  name). 

Now  you  are  ready  to  create  the  accounts. 

Step  2.  Create  XML  File  Containing  Reseller  Plan  Data 

Note:  Skip  this  step  if  you  are  migrating  only  master  admin's  end  users. 


Create  XML  files  for  the  reseller  plans  to  be  migrated.  If  you  migrate  from  Parallels  hl- 
Sphere,  use  the  PianExtractor  utility.  Otherwise,  create  plan  XML  according  to  our 
documentation.  Please  refer  to  Migrating  Plans  with  XML  (on  page  424)  for  details. 

In  this  section: 


Migrating  Plans  with  XML 
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Migrating  Plans  with  XML 

Plan  settings  are  stored  in  XML  format,  which  allows  extracting  and  moving  them  to 
other  locations. 

Migratable  Plans.  Migratable  plans  include  all  non-reseller  plans,  namely:  Unix, 
Windows,  Admin,  MySQL,  E-Mail,  Unix  Real  Server,  Windows  Real  Media.  All  end  user 
plans,  including  those  of  master  admin  and  resellers,  are  migratable. 

Migration  Tools.  Plans  are  migrated  with  two  Java  classes,  PianExtractor  and 
PlanCreator,  located  in  the  ~cpanel/shiva/psoft/hsphere/migrator/ 

directory. 

1)  PianExtractor  is  a Java  utility  to  extract  Parallels  H-Sphere  plans  into  XML  format. 
Extracted  plans  are  stored  in  the  plans  .xml  file. 

2)  PlanCreator  is  a tool  for  importing  plans  to  a new  CP  from  the  file  plans . xml  with 
plans  extracted  by  PianExtractor. 

Also,  you'll  need  to  place  the  following  files  in  the 

~cpanel/ shiva/psoft/hsphere/migrator/  directory: 

■ plans. xml  (http://hsphere.parallels.com/HSdocumentation/xmls/plans.xml)  - XML- 
formatted  information  about  plans  extracted  by  PianExtractor. 

■ plans.dtd  (http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd)  - DTD 
scheme  for  plans . xml. 

■ migrate_pians . log  - messages  about  errors  occurred  during  plan  extraction. 


In  this  section: 


Plan  Extractor 425 

Plan  Creator 425 

XML  Document  Structure 426 

XML  Elements  and  Attributes 427 
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Plan  Extractor 

Log  into  CP  server  as  cpanel  (on  page  65)  and  run  PianExtractor: 

java  psoft . hsphere . migrator . PianExtractor  [-force]  -resellername 
res_name  [-plans  the  list  of  plan  names ] [-ids  the  list  of  plan  ids ] 

Options: 

- The  -force  option  is  used  to  ignore  all  possible  errors  while  extracting  plans. 

■ The  -resellername  option  requires  the  username  of  the  reseller  whose  plans  are 
extracted.  To  extract  plans  for  master  admin,  use  option  -resellername  admin. 

■ The  -plans  option  requires  names  of  plans  to  be  extracted  for  this  reseller.  If  a 
plan  name  contains  spaces,  it  must  be  quoted,  e.g.: 

-plans  Unixl  'Reseller  2'  WinBest33 

If  you  omit  both  -plans  and  -ids,  all  plans  will  be  extracted. 

- The  -ids  option  requires  IDs  of  plans  to  be  extracted  for  this  reseller.  If  you  omit 
both  -plans  and  -ids,  all  plans  will  be  extracted. 

Examples: 

java  psoft . hsphere .migrator . PianExtractor  -force  -resellername  RESELLER 
-plans  silver  'unix  gold' 

java  psoft . hsphere .migrator . PianExtractor  -force  -resellername  RESELLER 
-ids  7564  7675 

java  psoft . hsphere .migrator . PianExtractor  -force  -resellername  RESELLER 
java  psoft . hsphere .migrator . PianExtractor  -resellername  admin  -plans 
silver  -resellername  RESELLER  -ids  7564 

PianExtractor  writes  error  messages  to  migrate  plans  . log. 


Plan  Creator 

Run  PlanCreator  as  cpanel  with  the  following  syntax: 

java  psoft . hsphere . migrator . PlanCreator  [-active]  -d  plans. xml  [- 
createprices ] 

Options: 

■ -active  - if  possible,  activate  plans  after  they  are  created. 

■ -d  plans. xml  - specify  plan  XML  file  to  be  taken. 

■ -createprices  - create  prices  for  plans. 

Make  sure  to  restart  Parallels  H-Sphere  (on  page  54)  after  running  PlanCreator. 
PlanCreator  writes  error  messages  to  migrate_plans  . log. 
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XML  Document  Structure 


The  structure  of  plans  .xml  looks  as  follows: 

plans 

/ ... 

plan 

/\ 

/ I \ 

periods  options  \ ... 

/ ...  | ... 

/\ 

period  / I \ / I I 

\ 

/ | \ resource  ifresource  ifgroup 

LogicalGroup 

/ I \ I I ...  I ... 

/ I \ I ...  _l_  I 

/ I \ I / \ / \ 

customparam  postparam  param  | resource  ifgroup  resource 

LogicalGroup 

/ I \ I I ...  I 

special  fields  price...  | ... 

/ \ 

special  resource  LogicalGroup 


Example  of  plans.xml:  http://hsphere.parallels.com/HSdocumentation/xmls/plans.xml 
DTD  Scheme:  http://hsphere.parallels.com/HSdocumentation/xmls/plans.dtd 
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XML  Elements  and  Attributes 

1 plan  - plan  description: 

■ name  - plan  name 

■ reseller  - reseller  name  (if  not  available,  admin  is  assumed) 

■ wizard  - wizard  name 

2 period  - plan  periods: 

■ id  - period  id 

■ size  - period  duration 

■ type  - period  type  (DAY,  WEEK,  MONTH,  YEAR) 

■ discountusage  - usage  discount  (%) 

■ discountsetup  - setup  discount  (%) 

■ discountunit  - recurrent  discount  (%) 

3 param  - plan  parameters  used  for  the  plan  creation: 

■ name  - parameter  name 

value  - parameter  value  Parameters: 

■ trial  - billing  type:  0 - Without  billing,  1 - Paid,  2 - Trial 

■ trial_duration  - trial  period  for  the  billing  type  trial 

■ trial  credit  - credit  limit  for  the  billing  type  trial 

■ hard  credit  - credit  limit 

■ send_invoice  - enable  e-mail  invoice  notification 

■ mixedip  - default  IP  type  (shared  or  dedicated) 

■ shared_ip_tag  - shared  IP  Tag 

■ caiias  - instant  alias  for  the  given  shared  IP  tag 

■ stopgapaiias  - stopgap  domain  for  the  given  shared  IP  tag 

■ money_back  - enable  money  back 

■ money_back_days  - money  back  guarantee  in  days 

■ periods  - the  number  of  plan  periods 

4 postparam  - parameters  to  be  set  after  the  plan  creation: 

■ name  - parameter  name 

value  - parameter  value  Parameters: 

■ contactinfo  - enable  contact  info 

■ biliinginf o - enable  billing  info 

■ _tempiate  - default  template 

■ templates  dir  - template  directory 
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5 customparam  - custom  parameters  to  be  set  after  the  plan  creation: 

■ name  - parameter  name 

■ value  - parameter  value 

6 resource  - resources  available  for  the  plan. 

Check  corresponding  plan  wizard  XML  documents  in  the 

'-cpanei/psoft/hsphere/pian/wizard/xmi/  directory  for  the  list  of  available 
resources  and  the  way  they  are  set: 

■ name  - resource  name 

■ enable  - is  resource  enabled 

■ include  - is  resource  included 

■ active  - is  resource  activated 

7 price  - resource  price: 

■ id  - price  id 

■ freeunits  - free  units 

■ setup  - setup  units 

■ unit  - monthly  units 

■ usage  - extra  units 

8 LogicalGroup  - the  plan's  logical  group: 

■ name  - logical  group  name 

■ type  - logical  group  type 

■ groupid  - logical  group  id 

9 special  - special  resource  parameters: 

■ name  - special  field  name 

■ value  - special  field  value 
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Step  3.  Prepare  The  Target  Control  Panel 

Before  you  start  creating  accounts  from  the  xml  files,  log  as  cpanel  user  (on  page  65), 

go  to  the  target  Parallels  H-Sphere  control  panel  and  do  the  following: 

1 Make  sure  that  the  names  of  the  plans  are  exactly  the  same  as  those 
in  your  user  data  xml  file.  To  get  a list  of  all  reseller  and  user  plans  in 
the  system,  run: 

java  psof t.hsphere. migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -dl  -pp 

2 In  the  xml  file,  find  users  that  have  empty  or  filled  mysql  tag.  In  the 
control  panel,  enable  MySQL  resource  for  the  plans  you  are  migrating 
these  users  to. 

3 If  you  intend  to  migrate  the  existent  user  content  into  Parallels  H- 
Sphere,  include  but  deactivate  Frontpage  in  all  plans  you  are 
migrating  your  customers  to,  and  in  which  FrontPage  will  be  used. 

4 If  you  want  to  preserve  original  billing  period  start  date,  make  sure 
that  the  billing  periods  have  the  same  duration  and  go  in  the  same 
order  as  those  in  your  old  control  panel. 


Step  4.  Create  Reseller  Plans 

Note:  Skip  this  step  if  you  don't  have  resellers. 


If  you  have  resellers,  run  PlanCreator  to  create  reseller  plans  on  the  target  Parallels  hl- 
Sphere  installation,  for  example: 

java  psof t . hsphere . migrator . PlanCreator  -active  -d  plans. xml 

Please  refer  to  Migrating  Plans  with  XML  (on  page  424)  for  details. 

Step  5.  Create  Resellers 

To  create  resellers,  run  ResellerUserCreator: 

java  psof t . hsphere . migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -1  migrate.log  -dl 
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Step  6.  Create  End  Users 

To  migrate  end  users,  run  CommonUserCreator: 

java  psoft . hsphere . migrator . CommonUserCreator  -d  migrate_users . xml  -1 
migrate . log  -dl 


Note:  To  prevent  double  charges  for  resources  billed  on  the  monthly  basis,  such  as 
Traffic  and  Disk  Usage,  CommonUserCreator  shifts  start  date  for  them  to  the  day 
before  the  date  of  migration. 


Troubleshooting 

If  the  migration  software  fails  to  create  a reseller/end  user  account,  it  will  return  an  error 
and  stop  the  migration.  In  this  case,  read  the  messages  on  the  screen  to  find  which 
user  caused  the  failure,  read  the  log  file  and  try  to  remove  the  cause  of  the  error. 


Note:  If  the  domain  tag  of  this  user  in  the  XML  file  contains  the  ip  attribute  and  if  the  IP 
in  this  user's  domain  was  created  before  the  error  occurred,  go  to  the  Parallels  hl- 
Sphere  control  panel  and  delete  this  IP. 


Then,  proceed  with  the  migration  using  the  above  command  plus  one  of  these  two 
options: 

■ -r  userjogin  - proceed  with  the  migration  starting  with  the  user  with  this  login 
name; 

■ -rc  userjogin  - delete  this  user  and  then  proceed  with  the  migration  starting  with 
this  user. 

The  full  command  must  look  like  this: 

a)  for  a reseller's  end  user: 

java  psoft . hsphere . migrator . ResellerUserCreator  -d 
migrate_resellers . xml  -1  migrate.log  -dl  -r  user_login 

b)  for  a direct  end  user: 

java  psoft . hsphere . migrator . CommonUserCreator  -d  migrate_users . xml  -1 
migrate . log  -dl  -r  user_login 
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Backup  and  Recovery 


This  chapter  explains  how  to  back  up  Parallels  H-Sphere  system  and  user  data. 

Backup  of  the  Control  Panel  server  with  the  PostgreSQL  system  database  is  done  by 
the  Parallels  H-Sphere  backup  script.  It  requires  PostgreSQL  client  version  7.3  or 
higher  installed  and  the  psql  program  available  in  the  system  paths  on  the  CP  server. 

Backing  up  content  on  the  Unix  servers  is  performed  manually.  See  the  backup  and 
recovery  list  (on  page  433)  of  Parallels  H-Sphere  related  directories  and  files. 

We  recommend  that  you  set  up  a separate  server  to  store  backup  archives. 

In  this  chapter: 


Backing  Up  Parallels  H-Sphere  Control  Panel  Server 432 

Parallels  H-Sphere  Backup  and  Recovery  List 433 

Recovering  Parallels  H-Sphere  Control  Panel 435 
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Restoring  the  Parallels  H-Sphere  System  Database  From  Backup 440 
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Backing  Up  Parallels  H-Sphere  Control 
Panel  Server 


This  section  explains  how  to  back  up  the  Control  Panel  server  with  the  system 
database  by  means  of  the  backup  script. 

The  backup  script  located  in  the  /hsphere/shared/backup  directory.  The  script 
includes  the  following  files: 

■ hs_bck  - the  main  script  file 

■ hs_bck.  cfg  - custom  configuration  file.  This  is  the  file  to  store  the  list  of  directories 
to  back  up. 

■ hs_bck.cfg.org  - default  configuration  file.  It  can  be  overwritten  with  Parallels  hl- 
Sphere  updates.  This  is  where  you  can  find  the  updated  list  of  parameters  to 
the  hs_bck  script  if  it  has  been  changed  in  a new  version. 

■ hs_bck . txt  - description/readme  file. 

You  need  to  configure  the  script  by  editing  the  hs_bck . cfg  file. 

> To  back  up  Parallels  H-Sphere  CP  server: 

1 Log  into  the  CP  server  as  root: 

su  - 

2 cd  into  the  backup  script  directory: 

cd  /hsphere/shared/backup 

3 Make  sure  the  files  hsjock . cfg  and  hs_bck . cfg.org  are  identical 
in  what  is  not  your  custom  settings.  The  format  of  the 
hs_bck.cfg.org  file  may  change  with  Parallels  H-Sphere  updates, 
and  it  is  important  to  ensure  that  the  backup  script  is  launched  with 
correct  parameters. 

4 In  hs_bck . cfg,  edit  the  list  of  directories  and  databases  to  back  up. 
See  the  backup  and  recovery  list  (on  page  433). 

5 In  hs_bck . cfg,  edit  the  the  backup  storage  directory,  the  number  of 
latest  backups  to  be  stored  (7  by  default),  the  log  file,  etc. 

6 Run  the  backup  script. 

■ For  regular  automatic  backups,  add  the  execution  of  the  hsjock  file  into  the  CP 
server  crontab  configuration  (on  page  33),  e.g.: 

<TIME>  /hsphe  re/shared/backup/hs  bck  hs  bck.cfg  2>&1  > 

/ dev/ null 

For  example,  to  run  the  backup  script  every  day  at  6:13  AM,  add  the  following 
line: 

13  6 * * * /hsphere/shared/backup/hs  bck 
/hsphere/shared/backup/hs  bck.cfg  2>&1  > /dev/null 
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■ For  additional  parameters  to  this  script,  please  run: 

/hsphere/ shared/backup/hs_bck 

System  DB  Dump 

In  addition  to  backing  up  the  pgsqi  directory  on  the  CP  server,  the  backup  script  can 
also  create  a dump  of  Parallels  H-Sphere  system  database  and  Parallels  SiteStudio 
databases.  For  this,  make  sure  the  following  directories  are  listed: 

PRO P_FILE 

/hsphere /local /home/ cpanel/ shiva /psof t_conf ig/ hsphere . properties 
PROP  FILE  /hsphere/ shared/ SiteStudio/psof t_conf ig/ counter . properties 
PROP  FILE  /hsphere/ shared/ SiteStudio/psof t__con fig /poll . properties 
PROP^FILE  /hsphere/ shared/ SiteStudio/psof t_conf ig/ guestbook . properties 

If  Parallels  Pi-Sphere  database  is  large,  the  dump  can  take  several  hours  to  complete. 
You  can  speed  it  up  by  setting  f sync=of  f 

in  postgresqi . conf . When  you  are  done,  unset  this  option  back  for  safety  reasons. 


Parallels  H-Sphere  Backup  and  Recovery 
List 


Following  is  the  list  of  directories  and  files  to  back  up  and  recover.  Backup  can  be  done 
by  means  of  the  Parallels  Fl-Sphere  backup  script  (on  page  432)  on  the  CP  server  or 
manually  on  other  Parallels  Fl-Sphere  servers. 


Item 

Comment 

Control  Panel  Server 

/hsphere /local /home/ cpanel /hsphere /WEB 
-INF/classes/psof t config/ 

Parallels  H-Sphere  configuration  and 
properties  files 

/hsphere/ shared/ SiteStudio/ studio/WEB- 
INF/classes/psoft  config/ 

Parallels  SiteStudio  configuration  and 
properties  files 

/hsphere /local /home /cpanel /apache /etc/ 

Apache  configuration  and  properties 
files 

/hsphere /local /home/ cpanel /hsphere /WEB 
-INF/ classes/ shiva -templates/ IMAGES/ 

Control  Panel  icons  and  images 

/hsphere /local /home/ cpanel /hsphere /WEB 
-INF/ classes /custom/ 

Custom  Control  Panel  templates,  etc. 

/ hsphere / shared/ SiteStudio/var/ website 
s/ 

Parallels  SiteStudio  user  data 

/var/ lib /pgsqi/ 

Parallels  H-Sphere  and  Parallels 
SiteStudio  system  databases  and 
database  settings 

/hsphere/local/home/ cpanel/ . kb/ 
/hsphere/local/home/ cpanel/ . attachment 
s/ 

Parallels  H-Sphere  knowledge  bases 

/hsphere/ local /home /cpanel/ shiva /packa 
ges 

Parallels  H-Sphere  packages 

Web  Server 


/hsphere/local/home/ 

User  Home  Directories 

/usr/ local /frontpage/ 

FrontPage  Extensions  settings 

/ hsphere /local/con fig/ 

httpd  and  ftp  configs 

/var/spool/cron/  (Linux) 

/var/cron/tabs/  (FreeBSD) 

Customer  Crontabs 

/hsphere/ shared/ apache/htdocs/phpMyAdm 
in/config.inc. php 

phpMyAdmin  configuration  file 

/hsphere/ shared/ apache/htdocs/phpPgAdm 
in/conf/config.inc. php 

phpPgAdmin  configuration  file 

/hsphere /local/ network/ 

ips  file,  etc. 

/hsphere/ shared/ awstats/wwwroot/ cgi- 
bin/ 

AWS  configs  et  al. 

Mail  Server 


/hsphere/ local /var/vpopmail /etc/ 

vpopmail  settings 

/hsphere/ local /var/vpopmail/ domains/ 

Mail  domains 

/ var/ qmail/ control/ 

Settings  for  qmail  addons 

/var/qmail /users/ 

qmail  users 

/ hsphere /I oca 1/con fig/ 

httpd  and  ftp  configs 

/var/lib/mysql/  (Linux) 

/var/db/mysql/  (FreeBSD) 

MySQL  databases  (used  to  store  user 
settings 

for  integrated  antispam  and  antivirus 
software) 

/ hsphere /shared/ apache /htdocs/ horde/ co 
nfig/conf. php 

Horde  settings 

DNS  Server 


/etc/named . conf 
/etc/rndc . conf 

Main  DNS  config  files 

/hsphere /local /var/ named/ 

DNS  zone  files 

MySQL  Server 

/var/lib/mysql/  (Linux) 

/var/db/mysql/  (FreeBSD) 

MySQL  settings  and  databases 

User  PostgreSQL  Server 

/var/lib/pgsql/  (Linux) 

/usr/local/pgsql/  (FreeBSD) 

User  postgres  settings  and  databases 
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Recovering  Parallels  H-Sphere  Control 
Panel 


This  document  provides  a general  outline  on  how  to  recover  Parallels  H-Sphere  Control 
Panel  to  a new  server  if  the  old  one  has  crashed  due  to  hardware  or  other  problems. 
We  will  be  looking  into  two  situations: 

■ You  have  been  having  hardware  problems  that  didn't  affect  the  HDD,  and  you  can 
access  the  HDD.  This  also  applies  to  hacked  servers.  In  this  case,  you'll  have  to 
mount  the  HDD  of  the  crashed  server  to  the  new  server  to  copy  below  system  data 
from  it. 

■ You've  had  a HDD  failure  and/or  the  HDD  is  inaccessible.  In  this  case,  you'll  have 
to  restore  below  system  data  from  a backup  (on  page  432). 

In  either  case  it  is  presumed  that  your  old  server  is  down  and  no  Parallels  H-Sphere 
servers  are  running. 

This  instruction  doesn't  give  file/directory  locations  for  FreeBSD,  because  Linux  is  the 
recommended  operating  system  for  the  CP  server. 

Step  1 . Prepare  for  the  Recovery 

1 On  the  target  server,  install  exactly  the  same  version  of  Parallels  H- 
Sphere  Control  Panel  as  on  the  source  server. 

2 Make  sure  the  source  and  target  servers  have  the  same  versions  of 
all  software  packages.  For  example,  make  sure  that  the  target  server 
has  the  same  version  of  PostgreSQL  as  the  source  server. 

3 Stop  Parallels  H-Sphere  CP  (on  page  54)  and  stop  PostgreSQL 
service  (on  page  55)  on  the  target  server. 

Step  2.  Recover  System  Data 

1 Log  into  the  target  server  as  root. 

2 Copy  files  and  directories  in  the  table  below  from  the  source  server  or 
backup  to  the  target  server. 

■ If  you  are  recovering  from  a backup  made  by  the  backup  script  (on  page  432), 
untar  the  backup  archive  copy  the  below  directories. 

■ If  you  are  recovering  data  from  the  HDD  of  the  crashed  server,  just  copy  the 
below  directories: 

rsync  -arlpogvzt  -e  ssh  SOURCE_SERVER_IP : DIRECTORY _PATH 
TARGET_DIRECTORY_PA  TH 
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3 Restore  the  backed  up  SSH  keys  from  the 

~cpanel /. s sh/ identity . pub  and  ~cpanel / . s sh/ id_dsa . pub 
into  the  /root/.ssh/ authori zed_keys  and 

/ root/  . ssh/ authorized_keys2,  respectively,  instead  of  the  new 
keys  generated  on  the  target  server  after  Step  1 . Please  refer  the 
Generating  SSH  Keys  for  Parallels  H-Sphere  Servers  (on  page  109) 
document  for  details. 

4 On  multiserver  Parallels  H-Sphere  cluster,  test  inter-server 
communication  via  SSH  without  login.  For  example: 

su  -1  cpanel 
ssh  root $cp_server_ip 

exit 

ssh  root@ second  server  ip 

exit 

and  so  on. 

5 Sometimes,  in  order  to  restore  some  core  templates  and  images,  you 
may  need  to  run  the  Parallels  H-Sphere  update  script  for  this  version 
with  the  hsonlycpupdate  option. 

6 Start  Parallels  H-Sphere  CP  (on  page  54)  and  PostgreSQL  (on  page 
55)  on  the  target  server. 

Note:  If  PostgreSQL  does  not  run  smoothly  after  its  start,  remove  the  the 

postmaster . pid  file  in  /var/lib/pgsql 

7 You  may  test  the  Parallels  H-Sphere  database  by  running: 

su  -1  cpanel  -c  ' psql  hsphere ' 

This  should  result  in  a successful  log  into  the  database  from  the  command  line. 


Files  and  Directories  To  Be  Recovered 


Item 

Comment 

-cpanel/shiva/psoft  config/ 

Parallels  H-Sphere  configuration  and 
properties  files 

/hsphere / shared/ SiteStudio/psoft  c 
onf ig/ 

Parallels  SiteStudio  configuration  and 
properties  files 

-cpanel /apache /etc/ 

Apache  configuration  and  properties  files 

-cpanel/ shiva/ shiva- 
templates/ IMAGES 

Control  Panel  icons  and  images 

-cpanel/ shiva/ custom 

Custom  Control  Panel  templates,  etc. 

/ hsphere / shared/ SiteStudio/var/ web 
sites 

Parallels  SiteStudio  user  data 

/var/lib/pgsql  (on  Linux) 

/var/db/pgsql or /usr/local/pgsql 

(on  FreeBSD) 

Parallels  H-Sphere  and  Parallels  SiteStudio 
system  databases  and  database  settings 
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-cpanel/ . kb/ 

-cpanel/ . attachments/ 

Parallels  H-Sphere  knowledge  bases 

-cpanel/ . ssh/identity .pub 
-cpanel/ . ssh/id  dsa.pub 

SSH  keys  to  be  restored  into  the 
/root/ . ssh/authorized  keys  and 
/root/ . ssh/authorized  keys2, 

respectively,  instead  of  the  new  keys 
generated  on  the  target  server  after  Step  1 
(fresh  Parallels  H-Sphere  installation). 

Recovering  Unix  Hosted  Parallels  H- 
Sphere  Servers 

This  document  explains  how  to  recover  non-CP  Linux/FreeBSD  boxes.  If  you  are 
restoring  CP,  see  Recovering  Control  Panel  (on  page  435). 


Important:  To  successfully  recover  a crashed  server,  you  must  meet  the  following 
requirements: 

1 . You  must  have  all  user  content  and  configuration  files  previously  backed  up  (on  page 
432). 

2.  You  must  have  the  physical  and  logical  server  structure  of  the  crashed  server 
preserved  in  the  administrator  CP  in  the  E. Manager  menu. 


We  suggest  the  procedure  below. 


In  this  section: 


Step  1 . Prepare  Crashed  Server  for  Recovery 438 

Step  2.  Run  Parallels  H-Sphere  Updater 438 

Step  3.  Run  the  Recovery  Tool 438 

Step  4.  Restore  User  Content 439 
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Step  1 . Prepare  Crashed  Server  for  Recovery 

1 Prepare  the  server  where  the  crashed  box's  services  and  content  are 
to  be  restored,  according  to  Parallels  H-Sphere  installation 
requirements  described  in  the  Installation  Guide. 

2 Make  sure  this  "blank"  server  is  bound  to  the  same  IP  the  crashed 
server  had. 

3 Place  the  cpanei  user's  public  SSH  keys  (on  page  109)  from  the  CP 
server  to  the  server  to  be  recovered  so  that  you  can  connect  via  SSH 
from  CP  server's  root  to  the  new  box  without  password. 


Step  2.  Run  Parallels  H-Sphere  Updater 

1 Log  into  the  CP  server  as  root: 

$ su  -l 

2 Download  the  update  script  of  the  Parallels  H-Sphere  version  you 
were  running  on  the  crashed  server.  If  you  already  have  an  older 
version  of  the  updater  in  the  current  directory,  please  remove  or 
rename  this  file  before  the  download. 

3 Run  the  updater  on  the  directory  where  you  have  downloaded  it.  See 
the  Update  Guide  for  details. 

4 Restore  the  crashed  server  software  by  typing  in  the  following 
command  in  the  updater's  command  line  prompt: 

hspackages  ips=<CRASHED_SERVER_IP> 


Step  3.  Run  the  Recovery  Tool 

Web,  Mail,  MySQL,  PgSQL  servers:  To  restore  your  Parallels  H-Sphere  physical 
resources  (Unix  users  and  configuration),  log  in  as  the  cpanei  user  (on  page  65)  and 
run  PhysicalCreator  (on  page  72). 


Note:  Do  not  confuse  the  account  ID  with  the  server  ID  you  used  when  generating 
configuration  files.  Account  IDs  could  be  found  in  the  accounts  table  of  the  Parallels  H- 
Sphere  system  database. 


DNS  server:  For  DNS  servers,  log  in  as  the  cpanei  user  (on  page  65)  and  run  DNS 
Creator  (on  page  211): 

java  psoft . hsphere . tools . DNSCreator  -m  db 
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Step  4.  Restore  User  Content 

To  restore  data  from  the  backup,  check  with  the  backup  and  recovery  list  (on  page  433) 
for  for  this  server.  Restore  listed  directories  from  /var /backup /<ARCHIVE> . tgz  or 
custom  backup  directory  into  the  appropriate  locations. 

More  on  backup  recovery  (on  page  440). 
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Restoring  Files  and  Directories  from 
Backup 

This  document  explains  how  to  recover  Parallels  H-Sphere  user  and  system  data  you 
have  backed  up  according  to  the  manual  on  backing  up  Parallels  H-Sphere  (on  page 
432). 

Parallels  H-Sphere  backup  location  is  set  in  the 

/hsphere/ shared/backup/hs_bck . cf g config  file.  The  default  location  is 

/ var/backup. 

hs_bck  stores  the  system  data  backup  (with  user  content  if  configured  in 
hs_bck.  cfg)  in  the  following  files  in  the  bck_dir  directory: 

■ <ARCHIVE> . tgz  - the  latest  backup;  <ARCHIVE>  is  the  name  of  the  backup  file  set  in 
hs_bck.  cfg.  This  is  the  default  name: 

BACKUP  hs_bck 

Older  backup  files  are  named  <ARCHIVE> . l . tgz,  <ARCHIVE> . 2 . tgz,  ... 

■ hsphere . sqi  - the  Parallels  H-Sphere  system  database  backup 

■ counter . sqi,  poll . sqi,  guestbook . sqi  - Parallels  SiteStudio  system 
databases  are  also  backed  up  if  Parallels  SiteStudio  is  set  up  with  Parallels  H- 
Sphere. 

To  restore  data  from  the  backup,  check  with  the  backup  and  recovery  list  (on  page  433) 
for  the  directories  that  need  to  be  recovered  for  this  server.  Restore  these  directories 
from  <ARCHIVE>.  tgz  into  the  appropriate  locations  on  the  server. 


Restoring  the  Parallels  H-Sphere  System 
Database  From  Backup 

This  documentation  explains  how  to  restore  the  Parallels  H-Sphere  system  database 
from  a backup  made  by  the  Parallels  H-Sphere  hs_bck  (on  page  432)  script.  If  you 
back  up  your  system  PostgreSQL  database  manually  using  pg_dump,  the  procedure 
would  be  basically  the  same,  except  for  the  backup  names  and  locations. 

The  backup  destination  directory  for  the  /hsphere/shared/backup/hs_bck  script 
is  set  in  the  /hsphere/ shared/backup/hs_bck .cfg  config  file.  The  default 
location  is: 

BCK  DIR  /var/backup 

hs_bck  stores  the  system  data  backup  in  the  following  files  in  the  bck_dir  directory: 

■ <ARCHIVE>Agz  - the  system  data  content;  <ARCHIVE>  is  the  name  of  the  backup  file 

set  in  hs  bck . cfg: 
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BACKUP  hs_bck 

Older  backup  files  are  named  <ARCHIVE> . l . tgz , <ARCHIVE> . 2 . tgz , ... 

■ hsphere . sql  - backup  of  the  Parallels  H-Sphere  system  database 

■ counter . sql,  poll . sql,  guestbook . sql  - Parallels  SiteStudio  system 
databases  are  also  backed  up  if  Parallels  SiteStudio  is  integrated  with  Parallels  hl- 
Sphere. 

Below  are  two  cases  restoring  the  database  depending  on  PostgreSQL  installed  or  not 
on  the  server. 


In  this  section: 

Restoring  the  Parallels  H-Sphere  Database  on  a Server  with  PostgreSQL  Not  Installed  442 
Restoring  the  Parallels  H-Sphere  Database  Content  if  PostgreSQL  Is  Installed :443 
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Restoring  the  Parallels  H-Sphere  Database  on  a Server 
with  PostgreSQL  Not  Installed 

1 Log  into  the  erver  as  root: 

su  - 

2 Install  PostgreSQL  to  the  server. 

3 Start  PostgreSQL  for  the  first  time: 

On  RedHat  servers: 

/ etc/ rc . d/ init . d/postgresql  start 

On  FreeBSD  servers,  you  need  to  initiate  the  PostgreSQL  service  database 
manually  before  you  start  Postgres: 

su  - pgsql  -c  initdb 

/usr/local/etc/ rc .d/010 .pgsql . sh  start 

4 Log  in  as  PosgreSQL  user: 

On  RedHat  servers  (the  PostgreSQL  service  database  is  initiated  automatically  on 
login): 

su  - postgres 
On  FreeBSD  servers : 
su  - pgsql 

5 Create  the  user  wwwuser: 
createuser  wwwuser 
Answer  yes  to  all  prompts. 

6 Enter  the  PostgreSQL  service  database: 

psql  templatel 

7 Restore  the  wwwuser  password: 

alter  user  wwwuser  with  password  ' old_pas sword ' ; 
alter  user  pgsql  with  password  ' old_j?as sword ' ; 

Here,  old_password  is  the  wwwuser  password  to  be  restored. 

8 Quit  from  PostgreSQL: 

\q 

9 Configure  PostgreSQL  passwords  in  the 

~pgsql/data/ pg_hba . conf  file,  according  to  instructions  provided 
in  this  file. 

10  Optimize  Postgres  (on  page  102)  for  better  PostgreSQL  performance 
on  powerful  servers,  esp.  when  the  database  is  large  (more  than 
1GB). 
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Note:  It  is  helpful  to  set  f sync=false  in  postgresql . conf  for  the  time  of 
recovery.  This  allows  to  speed  up  the  process.  However,  please  beware  that  this 
may  damage  the  database  integrity,  and  we  recommend  using  this  option  only  on 
reliable  hardware!  Don't  forget  to  return  to  fsync=true  after  the  recovery  is 
complete! 

11  Restart  PostgreSQL  (on  page  55). 

12  Create  Parallels  H-Sphere  database  by  running: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 
Parallels  SiteStudio  databases  are  created  in  the  similar  way. 

13  Import  the  database  content  from  the  backup: 

psql  -U  wwwuser  -f  <HS_BCK>/ hsphere . sql  hsphere 

where  <HS_BCK>  is  the  backup  directory.  Parallels  SiteStudio  databases  are 
imported  in  the  similar  way. 

Restoring  the  Parallels  H-Sphere  Database  Content  if 
PostgreSQL  Is  Installed: 

1 Log  in  to  the  CP  server  as  root: 

su  - 

2 Drop  the  Parallels  H-Sphere  database: 

dropdb  -U  wwwuser  hsphere 

3 Create  the  Parallels  H-Sphere  database: 

createdb  -E  UNICODE  -U  wwwuser  hsphere 

4 Optimize  Postgres  (on  page  102)  for  better  PostgreSQL  performance 
on  powerful  servers,  esp.  when  the  database  is  large  (more  than 
1GB). 

Note:  It  is  helpful  setting  f sync=faise  in  postgresql . conf  for  the  time  of 
recovery.  This  allows  to  speed  up  the  process.  However,  please  beware  that  this 
may  damage  the  database  integrity,  and  we  recommend  using  this  option  only  on 
reliable  hardware!  Don't  forget  to  return  to  fsync=true  after  the  recovery  is 
complete! 

5 Import  the  database  content  from  the  backup: 

psql  -U  wwwuser  -f  <HS_BCK>/ hsphere.  sql  hsphere 
where  <HS_BCK>  is  the  backup  directory. 

Parallels  SiteStudio  databases  are  restored  in  the  same  way. 
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Fixing  Crashed  Parallels  H-Sphere 
Database 


Sometimes  PostgreSQL  database  can  get  corrupted  to  the  point  of  no  return.  That 
might  manifest  itself  in  things  like: 

hsphere=#  VACUUM  ; 

ERROR:  Relation  71343  does  not  exist 

This  usually  means  that  index  is  corrupted. 

> To  recover  from  the  problem: 

1 Login  as  root: 

su  - 

2 Stop  Postgres  (on  page  54)  if  it  is  running. 

3 Make  sure  that  no  Postgres  processes  are  running  using  the 
command: 

ps  auxw  | grep  post 

If  any  of  them  are  running,  kill  them. 

4 Remove  Postgres'  pid  file: 

rm  -f  PGSQL_HOME/data/postmaster . pid 

From  now  on,  we  note  PGSQL_HOME  as  the  Postgres  home  directory  which  is 

/var/lib/pgsqi  on  RedHat  servers,  and  /usr/iocai/pgsqi  on  FreeBSD. 

5 Switch  to  Postgres  user: 

# su  - postgres  (on  RedPlat) 

# su  - pgsql  (on  FreeBSD) 

6 Backup  PostgreSQL  database  stored  in  the  pgsql_home/ data 
directory: 

cp  -r  PGSQL_HOME/data  pgdata . backup 

7 Try  to  connect  to  the  Parallels  H-Sphere  database  in  single  mode: 

postgres  -D  PGSQL_HOME/data  -O  -P  hsphere 

There  can  be  errors  like: 

FindExec:  found  " /usr/bin/postmaster"  using  argv[0] 

2002-03-22  13:42:46  [6002]  DEBUG:  database  system  was  shut  down  at 
2002-03-22  11:46:11  CET 

2002-03-22  13:42:46  [6002]  DEBUG:  ReadRecord:  invalid  resource  manager 
id  157  at  (0,  561372168) 

2002-03-22  13:42:46  [6002]  DEBUG:  Invalid  primary  checkpoint  record 
2002-03-22  13:42:46  [6002]  DEBUG:  Invalid  RMID  in  secondary  checkpoint 
record 
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2002-03-22  13:42:46  [6002]  FATAL  2:  Unable  to  locate  a valid  Checkpoint 
record 

2002-03-22  13:42:46  [6002]  DEBUG:  proc_exit(2) 

2002-03-22  13:42:46  [6002]  DEBUG:  shmem  exit(2) 

2002-03-22  13:42:46  [6002]  DEBUG:  exit(2) 

/usr/bin/postmaster : reaping  dead  processes... 

/usr/bin/postmaster : Startup  proc  6002  exited  with  ... 

The  messages  like: 

ReadRecord:  invalid  resource  manager 

and  other  are  culprit  of  the  error. 

In  case  of  the  above  errors,  do  the  following: 

1 Execute: 

pg_resetxlog  PGSQL_HOME/data 

(this  will  reset  the  write-ahead  log  and  other  control  information  of  a PostgreSQL 
database  cluster;  they  are  important  but  this  is  the  only  way  to  recover). 

2 Try  to  log  into  Postgres  again  in  single  mode: 

postgres  -D  PGSQL_HOME/data  -O  -P  hsphere 

3 Once  you  are  in,  type: 

reindex  database  hsphere; 

4 Exit  the  database: 

\q 

5 Finally,  start  Postgres  (on  page  54)  and  see  if  everything  is  working. 
Here,  two  Postgres  tools  are  used: 

■ reindex  database  to  recover  corrupted  indexes 

■ pg_resetxiogs  to  reset  write-ahead  log  files  and  the  state  of  Postgres. 


Backing  Up  Winbox 

This  document  explains  how  to  back  up  your 

■ Windows  server  settings  stored  in  the  MetaBase, 

■ MS  SQL  database 

■ user  content 

In  this  section: 


Backing  Up  the  Metabase 446 

Backing  Up  MS  SQL  Databases 446 

Backing  Up  User  Content 446 
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Backing  Up  the  Metabase 

1 Go  to  Start  ->  Programs  ->  Administrative  Tools  ->  Computer 
Management. 

2 In  the  left  tree,  unfold  Services  and  Applications. 

3 Right-click  Internet  Information  Services  and  select  Backup/Restore 
Configuration. 

4 In  the  window  that  appears,  click  Create  Backup. 

Usually,  IIS  metabase  backup  files  are  located  in  the  following  directory: 

C : \WINNT\system32\inetsrv\MetaBack\ 

Backing  Up  MS  SQL  Databases 

1 Go  to  Start  ->  Programs  ->  Microsoft  SQL  Server  ->  Enterprise 
Manager. 

2 Unfold  the  left  menu  tree  until  you  see  the  name  of  the  logical  server. 
Click  it. 

3 Click  Tools  on  the  toolbar  and  select  Backup  Database. 


Backing  Up  User  Content 

1 Go  to  Start  ->  Programs  ->  Accessories  ->  System  Tools  ->  Backup. 

2 Select  Backup  Wizard 

3 On  the  first  step  of  the  wizard,  select  Back  up  selected  files,  drives,  or 
network  data. 
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Recovering  Winbox 

This  document  explains  how  to  restore  Parallels  H-Sphere  Winbox  configuration  using 
the  Physical  Creator  (on  page  72)  utility.  If  you  have  access  to  user  homes,  you  can 
recover  user  content  from  this  directory.  If  you  don't,  you'll  need  an  earlier  backup  (on 
page  445)  with  preserved  directory  structure  (on  page  239). 

We  suggest  the  recovery  procedure  below. 


In  this  section: 


Step  1.  Back  Up  User  Content 448 

Step  2.  Install  Parallels  H-Sphere 448 

Step  3.  Set  Up  Dedicated  IPs 448 

Step  4.  Prepare  Target  Winbox  for  Physical  Creator 449 

Step  5.  Run  PhysicalCreator  on  the  CP  Box 449 

Step  6.  Restore  Content  from  Backup 450 

Step  7.  Install  Shared  SSL 450 

Step  8.  Set  Correct  NTFS  Permissions  and  Owner  for  the  Home  Directory 451 
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Step  1 . Back  Up  User  Content 

1 Stop  IIS  by  running  the  following  commands  from  the  command 
prompt: 

iisreset  /stop 
net  stop  w3svc 
net  stop  ftp 

2 Rename  the  directory  containing  Parallels  H-Sphere  user  homes.  It 
will  be  used  later  to  recover  user  content.  If  you  don't  have  access  to 
user  homes,  you'll  have  to  recover  user  content  from  a backup. 

3 Start  IIS: 

iisreset  /start 

4 Create  an  empty  HSHOME  directory 

Step  2.  Install  Parallels  H-Sphere 

1 Make  sure  to  have  IIS  (WebService)  and  FTP  (IIS  or  Serv-U)  installed. 
For  information  on  IIS,  run  from  the  command  prompt: 
%SystemRoot%\System32\Inetsrv\iis .rase 

For  information  on  Serv-U  FTP,  check  the  task  manager  or  Service  Managere  (full 
name  : Serv-U  FTP  Server,  short  name:  servu) 

FTP  can  be  missing  if  the  server  is  running  only  MS  SQL. 

2 Follow  Winbox  preinstallation  procedure  as  suggested  in  the  Winbox 
Installation  Guide. 

3 Follow  Winbox  installation  procedure. 

4 After  the  installation,  set  up  WebShell4. 

Step  3.  Set  Up  Dedicated  IPs 

1 Go  to  the  Parallels  H-Sphere  admin  control  panel  and  select  the 
Winbox  in  L. Servers  of  the  E. Manager  ->  Servers  menu. 

2 Copy  all  Busy  Dedicated  IPs  and  their  netmasks  from  the  list  of  IPs 
into  a text  file  the  IPs  to  create  a file  with  the  following  format: 

192.0.34.166  255.255.255.0 
160.79.224.130  255.255.255.0 
81.3.94.100  255.255.255.0 

3 Download  IpCreator: 

http://download.hsphere.parallels.com/shiv/WinBox/ipcreator.exe. 

4 Bind  IPs  using  the  IpCreator  utility,  passing  the  file  with  IPs  as  a 
parameter: 

IpCreator.exe  FILE_WITH_IPS  > log.txt 
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Step  4.  Prepare  Target  Winbox  for  Physical  Creator 

1 In  the  command  prompt  of  the  Winbox  server,  run: 
net  stop  HsQuotas 

2 Remove  the  content  of  the  HSphere\skeleton  directory. 

3 Put  file  skeleton_empty.exe 

(http://download.hsphere.parallels.com/shiv/WinBox/skeleton  empty.e 

xe)  in  the  HSphere\skeleton  directory. 

4 Run  skeleton_empty . exe  with  the '-dir  ' parameter: 
skeleton_empty.exe  -dir 

Note:  when  you  finish  the  recovery,  make  sure  you  restored  skeleton  by  means  of 
Parallels  H-Sphere  updater  for  your  version:  hs ins t<your_hs_version> . exe 


Step  5.  Run  PhysicalCreator  on  the  CP  Box 

1 Go  to  the  Parallels  H-Sphere  admin  control  panel,  select  P.Servers  of 
the  E.Manager  ->  Servers  menu,  and  click  server  info  for  the  Winbox  in 
question. 

2 Check  if  server  info  shows  on  the  page  that  appears.  If  not,  the  CP 
server  can't  communicate  with  the  Winbox;  make  sure  to  fix  this  issue 
before  proceeding. 

3 Downolad  tail  utility  for  Windows 
(http://download.hsphere.parallels.com/shiv/WinBox/tail.exe)  and  put  it 
into  the  windows  (win2003)  or  winnt  (win2000)  directory. 

4 Log  into  the  system  database  (on  page  65)  and  run  the  following  DB 
query  to  find  out  the  number  of  domains  to  create: 

select  count (*)  from  iis  vhost  i, parent  child  p, accounts 
a, user  account  ua  where  i.id=p. child  id  and  p. account  id  = 
a. id  and  a. deleted  is  null  and  ua. account  id  = a. id  and 
(a. demo  <>  1 OR  demo  IS  NULL)  and  host  id  = ???; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

5 Run  PhysicalCreator  as  the  cpanel  user  (on  page  65): 

java  -Xms64M  -Xmx512M  psoft . hsphere . tools . PhysicalCreator  -rg 
winweb  -co  -lid  LOGICAL_SERVER_ID  > creator.log  2>&1  & 

6 In  the  command  line  on  the  Winbox,  run  tail  -f  action.log  to 
monitor  the  creation  of  Winbox  resources. 

7 In  another  command  line  window,  periodically  check  the  number  of 
created  domains  by  running: 

find  "CreateWebHost ( " <HS  DIRECTORYR\logs\action.log  /c 

for  example: 

find  "CreateWebHost ( " d:\hsphere\logs\action.log  /c 
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Step  6.  Restore  Content  from  Backup 

1 Update  Parallels  H-Sphere  to  restore  original  skeleton  and  renamed 
scripts. 

2 Back  up  IIS  metabase  using  built-in  IIS  backup  tools. 

3 Stop  IIS: 

iisreset  /stop 
net  stop  w3svc 
net  stop  ftp 

4 Copy  user  content  to  the  directory  for  user  homes. 

5 Start  IIS: 

iisreset  /start 

6 In  the  command  prompt  of  the  Winbox  server,  run: 
net  start  HsQuotas 

Step  7.  Install  Shared  SSL 

1 In  the  admin  control  panel,  install  completely  new  Certificate  key  and 
file  pair  as  described  in  Parallels  H-Sphere  Service  Administrator 
Guide.  You  can  get  them  in 

/hsphere/ shared/ apache / conf  / ssl . shared/ <domain.name>/  on 

any  Unix/Linux  web  server.  This  will  repost  the  wildcard  certificate  on 
all  servers,  including  the  Winbox  you  are  recovering. 

2 Download  Recreation  scripts 

(http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScri 

pts.zip)  in  a zip  archive  and  unpack  them  to  a separate  directory  on 
the  Winbox,  for  example  recreation_scripts. 

3 Log  into  the  system  database  (on  page  65)  and  run  the  following  DB 
query  to  select  the  domain  names  with  shared  SSL  enabled: 

select  s . name , hostnum, d . name  from  shared  ssl  s,  parent  child 
pi,  parent  child  p2 , domains  d,  iis  vhost  h where  s.id  = 
pi . child  id  and  pi. parent  id  = p2. child  id  and  p2. parent  id  = 
d.id  and  p2. child  id  = h.id  and  h.host  id=  ???; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

4 Copy  results  of  the  query  into  a text  file  in  the  recreation_scripts 
directory  and  name  it,  for  instance,  S_SSL.txt.  It  will  have  the 
following  format: 


snamel 

| hostnuml 

domain  namel 

sname2 

| hostnum2 

domain  name2 

snameN 

| hostnumN 

domain  nameN 

where: 

snamex  is  the  third  level  domain  secured  with  the  wildcard  certificate,  e.g. 

user22 . yourdomain . com 
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hostnumx  is  the  domain  ID  in  IIS 

domain_namex  is  the  corresponding  second  level  domain,  e.g.  user22.com. 

5 Enter  the  recreation_scripts  directory  and  run  the  following 
command: 

sslprepare.bat  %1  %2  %3  %4  %5  > SetSSL.txt 
where: 

rem  %i  is  the  file  name  you  have  created  (e.g.  s_ssl  . txt) 
rem  %2  - WinbOX  IP 

rem  %3  - Service  domain  used  for  shared  SSL 

rem  %4  - Parallels  H-Sphere  login  used  at  Winbox  installation 

rem  %5  - Parallels  H-Sphere  password  used  at  Winbox  installation. 

6 Open  SetssL . txt  and  remove  the  first  part  leaving  only  the  list  of 
links. 

7 Run  the  following  command: 

WGET.EXE  -i  SetSSL.txt 

This  will  recreate  all  Shared  SSL  resources  on  the  Winbox. 


Step  8.  Set  Correct  NTFS  Permissions  and  Owner  for 
the  Home  Directory 

1 Download  SetScrt  Tool: 

http://download.hsphere.parallels.com/shiv/WinBox/SetScrtNs20.exe 

2 Run  it  to  set  correct  owner  and  NTFS  permissions  on  user  home 
directories: 

SetScrtNs20  /f tp : <number>  /users :<file> 
where: 

ftp  - default  Parallels  H-Sphere  ftp  host  number 
users  - user  list  file 

3 Check  the  log  files  for  report. 

Note:  Read  on  NTFS  Permissions  (on  page  268) 
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Recovering  Winbox  Quota 

> To  recover  Winbox  quota: 

1 Download  Recreation  scripts 

(http://download.hsphere.parallels.com/shiv/WinBox/ReCreateAddScri 

pts.zip)  in  a zip  archive  and  unpack  them  to  a separate  directory  on 
the  Winbox,  for  example  recreation_scripts. 

2 Log  into  the  system  database  (on  page  65)  and  run  the  following  DB 
query  to  select  the  users  and  their  space  limit: 

select  unix  user. login,  quotas. size  mb  from  unix  user, 
parent  child,  quotas  where  hostid=???  and 
parent  child. parent  id=unix  user. id  and 
parent  child. child  id=quotas . id  and 
parent  child. child  type=4001; 

replacing  ???  with  the  ID  of  the  logical  server  you  are  recovering. 

3 Copy  results  of  the  query  into  a text  file  in  the  recreation_scripts 
directory  and  name  it,  for  instance,  quotat.txt. 

4 Enter  the  recreation_scripts  directory  and  run  the  following  command: 
Rquota.bat  %1  %2  %3  %4  > quota.txt 

where: 

rem  %l  - file  name,  e.g.  quota.txt 
rem  %2  - Winbox  IP 

rem  %3  - Parallels  H-Sphere  login  used  at  Winbox  installation 
rem  %4  - Parallels  H-Sphere  password  used  at  Winbox  installation 

5 Open  quota . txt  and  remove  the  first  part  leaving  only  the  list  of 
links. 

6 Run  the  following  command: 

WGET.EXE  -i  quota.txt 

This  will  recreate  quota  resource  on  the  Winbox. 
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Like  all  third  party  commercial  products,  Miva  Empresa  and  Miva  Merchant  are 
purchased  and  installed  separately  from  Parallels  H-Sphere.  Miva  Merchant 
(http://www.miva.com/products/merchant)  requires  Miva  Empresa 
(http://www.miva.com/products/empresa)  also  known  as  Miva  Virtual  Machine  or 
'mivavm'  for  web  server  XML  scripting,  e-commerce  and  database  capabilities. 

■ Miva  Merchant  5.x  is  supported  starting  with  Parallels  H-Sphere  2.4.3  Patch  1 
inclusive.  It  requires  Miva  Empresa  5.02  and  higher. 

■ Miva  Merchant  4.14  and  later  is  supported  from  Parallels  H-Sphere  2.3  RC  4 
inclusive.  It  requires  Miva  Empresa  4.02  and  higher. 

For  extensive  coverage  of  Miva  products,  please  visit  http://www.miva.com/products. 

In  this  chapter: 


Miva  Installation  for  *nix 453 

Miva  Installation  for  Windows 458 

Updating  Miva  4 to  Miva  5 459 


Miva  Installation  for  *nix 
Requirements 

■ Installed  and  properly  configured  Parallels  H-Sphere  system. 

■ One  valid  Miva  Empresa  license. 

■ At  least  one  valid  Miva  Merchant  license. 

In  this  section: 


Miva  Empresa  Installation 454 

Miva  Merchant  Installation 457 
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Miva  Empresa  Installation 

> To  install  Miva  Empresa: 

1 Log  into  the  web  server  as  root. 

2 Change  directory  to  /hsphere/shared/miva.  If  you  don't  have  this 
directory,  create  it  first  and  set  ownership  to  root : root  and 
permissions  to  755: 

mkdir  /hsphere/shared/miva 

chown  root: root  /hsphere/shared/miva 

chmod  755  /hsphere/shared/miva 

3 Download  Miva  virtual  machine  distribution  file  from 
http://www.miva.com/products/empresa/download/  to 

/hsphere/shared/miva. 

Linux:  mivavm-vX.  XX-linux  glibc2  . tar  . gz 
FreeBSD:  mivavm-vX . XX-freebsd  45.tar.gz 

Here,  mivavm  is  the  product  name,  vx.xx  its  version  name,  iinux_giibc2  is 
Linux  glibc2  package,  freebsd_45  is  FreeBSD  4.5  operation  system. 

4 Untar  the  unloaded  file: 

tar  xfz  <DistributionFileName> 

5 Move  the  content  of  the  directory  mivavm-vX. xx  to 
/hsphere/shared/miva: 

mv  mivavm-vX . XX/*  . 
rm  -rf  mivavm-vX. XX 

6 Set  ownership  to  root:root  on  the  content  of  the  directory 

/hsphere/shared/miva: 

chown  -R  root: root  /hsphere/shared/miva 

7 Move  file  cgi-bin  / mivavm-vX . xx  to  directory 
/hsphere/shared/miva: 

mv  cgi -bin/mi vavm- vX . XX  mivavm 

8 If  you  need  to  use  commerce  libraries  you  got  from  Miva,  copy  them 
to  directory  lib/commerce,  then  create  links  to  them  as  follows: 

In  -s  /hsphere/ shared/mi va/lib/commerce/uupsrss-vX . XX-linux- 
glibc2 . so 

/hsphere/ shared/mi va/lib/ commerce/uupsrss . so 

In  -s  /hsphere/ shared/mi va/lib/commerce/cybercash-vX . XX-linux- 
glibc2 . so 

/hsphere/ shared/mi va/ lib/ commerce/ cybercash . so 

In  -s  /hsphere/ shared/mi va/lib/commerce/ics2-vX . XX-linux- 

glibc2 . so  /hsphere/ shared/mi va/lib/ commerce/ ics2 . so 

In  -s  /hsphere/ shared/mi va/lib/commerce/linkpoint-vX . XX-linux- 

glibc2 . so 

/hsphere/ shared/mi va/lib/ commerce /linkpoint . so 
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In  -s  /hsphere/shared/miva/lib/commerce/authnet-vX . XX-linux- 
glibc2 . so 

/hsphere/ shared/mi va/ lib/ commerce/authnet . so 

9 If  you  have  more  than  one  web  server,  repeat  the  above  steps  for  all 
web  servers  where  you  want  to  have  Miva  installed. 

When  the  Miva  Empresa  resource  is  turned  on: 

■ In  the  domain  home  directory 

(/ hsphere /local /home /<user_name>/<domain_name> /),  the  cgi-bin  is 

createdthe  mivavm  and  mivavm.  conf  files  are  copied  to  this  cgi-bin  directory 

■ the  libmivaconf  ig . so  Symlink  to 

/hsphere/ shared/miva/lib/ conf  ig/3x . so  is  created  there 

■ In  the  user  home  directory  (/hsphere/iocai/home/<user_na/ne>/),  create  the 
mivadata  directory,  and  the  <domain_name>  subdirectory  there,  with  the  same 
name  as  the  domain  subdirectory  in  the  user  home  directory. 

■ In  the  Apache  configuration  file  for  this  domain,  the  Miva  compiled  script  MIME  type 
is  added: 

application/x-miva-compiled  .mvc 

Here, 

- mivavm  is  a CGI  application  that  executes  complied  Miva  scripts; 

- mivavm.  conf  is  the  Miva  Empresa  configuration  file. 

The  mivavm.  conf  file  may  look  like  this: 

mivaroot=& [ document  root] 

stdmodedatadir= /hsphere /local /home /miva /mi vadat a/mi va . com 

securityoptions=15 

< COMMERCE -LIB  METHOD=  "UPSCost" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ upsrss . so"> 

< COMMERCE -LIB  METHOD=  "CyberCash" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ cyber cash . so"> 

< COMMERCE -LIB  METHOD=  "ICS2" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ ics2 . so"> 

< COMMERCE -LIB  METHOD=  "LinkPoint" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ linkpoint . so"> 

< COMMERCE -LIB  METHOD=  "AuthorizeNet" 

LIBRARY=" /hsphere/ shared/miva/lib/ commerce/ authnet . so"> 
<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/miva/lib /built ins/ crypto.so"> 

<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/miva/lib /built ins/ system . so"> 
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<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/ miva /lib /built ins/ file. so "> 

<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/ miva /lib /built ins /math . so"> 

<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/mi va/ lib /built ins/ string. so "> 

<BUILTIN-LIB  LIBRARY  = 

" /hsphere/ shared/ miva /lib /built ins/ time . so"> 
cadir=/hsphere/ shared/miva/ certs 
opens sl=/ us r/ lib/ libs si . so 
opens sl_crypto=/usr/lib/libcrypto . so 

where: 

■ mivaroot  is  the  Miva  Web  root  directory,  the  same  as  the  domain's 
DocumentRoot  directory 

■ stdmodedatadir  is  a directory  where  Miva  Empresa  data  is  stored 

■ commerce-lib  method  is  a Payment  Instrument,  a commercial  library  to  support 
automatic  payments  from  credit  cards  via  merchant  gateway 

■ builtin-lib  library  is  a standard  (built-in)  library  that  contains  basic  system 
functions 

■ cadir  is  a directory  with  SSL  certificates 

■ openssi  is  the  path  to  the  OpenSSL  library 

■ opens  sl_cryp to  is  the  path  to  encryption  libraries 
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Miva  Merchant  Installation 

> To  install  Miva  Merchant: 

1 Log  into  the  web  server  as  root. 

2 Copy  file  Merchant-vY  . YY-bundle  . tar  . gz  to 
/hsphere / shared/miva.  vY . YY  is  Miva  Merchant  version. 

3 Create  a link  to  Merchant-vY  . YY-bundle  . tar  . gz: 

In  -s  /hsphere/ shared/mi va/Merchant-vY . YY-bundle . tar . gz 
Merchant-bundle 

4 In  the  admin  control  panel,  select  Globals  in  the  Plans  menu  and  make 
sure  Miva  Empresa  Engine  and  MIVA  Resource  are  enabled. 

5 Select  L.Servers  in  the  E. Manager  ->  Servers  menu,  then  click  the  web 
server,  and  at  the  bottom  of  the  page  that  appears  select  the  version 
of  Miva  Merchant: 


Additional  options 

Miva  Merchant 

version 

Miva  Merchant  v5. 00  or  later  Set  | 

Location  of  Miva 
Merchant  bundle 

|C:\MivaMerchant  + Set  | 

6 If  you  have  more  than  one  web  server,  repeat  the  above  steps  for  all 
web  servers  where  you  want  to  have  Miva  installed. 

7 Log  into  your  admin  Control  Panel,  select  Miva  Merchant  Lie.  in  the  3rd 
partyTools  menu  and  enter  your  Miva  Merchant  licenses  : 

Notes: 

■ Login  and  Password  for  Miva  admin  interface  are  the  same  as  for  FTP  unless  a 
user  has  activated  the  original  Miva  Merchant  setup. 

■ If  Miva  is  enabled,  the  user  can't  remove  the  cgi-bin  directory  and  CGI  handler  with 
the  . cgi  extension  in  Parallels  H-Sphere. 

■ mivadata  and  all  its  content  is  not  removed  when  Miva  resource  is  removed. 

■ To  make  Miva  work  via  SSL  (htpps),  an  SSL  certificate  is  required.  If  a user  cannot 
connect  to  Miva  site  by  SSL  (https://),  log  into  your  Miva  Merchant  control  panel  via 
http,  go  to  the  Domain  Settings  page  ->  Site  configuration  tab  and  check  secure 
URLs. 

■ You  can  install  two  instances  of  Miva  on  one  logical  server,  one  version  4.12  and 
older,  the  other  4.14  or  later. 

■ To  enable  Miva  Merchant  Follow  Symlinks  in  mivaroot  and  stddatadir,  you 
need  to  add  the  following  line  into  the  miva.conf  file: 

securityoptions=15 
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Miva  Installation  for  Windows 


It  is  recommended  to  install  Miva  products  prior  to  Parallels  H-Sphere  Winbox  software. 
If  you  choose  to  do  so,  simply  install  Miva  Empresa  and  Miva  Merchant  following  Miva 
documentation.  Afterwards,  install  Parallels  H-  Sphere  winbox  software,  and  the 
installation  wizard  will  guide  you  through  the  Miva  configuration  procedure. 

> To  install  Miva  on  a running  Winbox: 

1 Install  Miva  Empresa  VM  as  described  at 
http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/install  miva  empresa  vm  on  windo 

ws  2000  server.htm. 

2 Install  Miva  Merchant  as  described  in  Miva  documentation  at 
http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/web  host  resources.htm. 

Note:  Since  version  3.1,  Parallels  H-Sphere  supports  only  Miva  5 for  Windows 
platforms.  If  you  move  to  Miva  5 and  need  to  upgrade  Miva  Merchant  stores,  follow 
the  instructions  at  http://docs.mivamerchant.com/en- 

US/merchant/WebHost/webhelp/upqrade  to  merchant  5 from  merchant  4.htm. 

3 Go  to  your  admin  control  panel,  select  E.Manager  ->  L.Servers,  click  the 
Windows  server,  and  at  the  bottom  of  the  page  that  appears  specify 
the  version  of  Miva  Merchant.  Specify  also  its  location  on  your  box: 


Additional  options 

Miva  Merchant 

version 

Miva  Merchant  v5. 00  or  later  _▼  Set  | 

Location  of  Miva 
Merchant  bundle 

|C:\MivaMerchant  + Set  | 
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4 Run  Parallels  H-Sphere  Update  Wizard  from  the  administrator  control 
panel. 

5 Optionally,  install  miva  commerce  libraries. 

6 Log  into  your  admin  Control  Panel,  select  Miva  Merchant  Lie.  in  the  3rd 
partyTools  menu  and  enter  your  Miva  Merchant  licenses. 

7 Enable  Miva  in  your  hosting  plans. 

Once  you  have  enabled  Miva,  users  can  turn  them  on  in  their  control  panels.  User's 
miva  login  and  password  are  same  as  for  FTP. 


Updating  Miva  4 to  Miva  5 

We  do  not  support  Miva  4 and  Miva  5 running  on  the  same  web  server.  To  upgrade 
Miva  Merchant  and  Miva  Empresa,  you  need  to  uninstall  version  4 and  then  set  up 
version  5.0. 

Since  these  two  versions  use  different  system  libraries,  customer  stores  also  need  to 
be  updated  to  Miva  5. 

To  update  the  stores,  please  use  Miva  tools,  as  we  do  not  provide  any  update  utilities. 
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Urchin 


This  chapter  describes  how  to  install  Urchin  4 and  Urchin  5 on  your  Parallels  H-Sphere 
servers. 

Urchin  4 and  5 can  be  installed  on  any  Parallels  H-Sphere  *nix  server.  It  does  not 
require  any  special  configuration  and  once  installed,  can  poll  statistics  from  all  web 
servers  and  winboxes. 

In  this  chapter: 


Urchin  4 and  5 Installation  on  Unix 461 

Urchin  4 and  5 Installation  on  Windows 463 

Urchin  4 And  Urchin  5 Database  Utilities 464 
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Urchin  4 and  5 Installation  on  Unix 

> To  install  Urchin: 

1 Go  to  the  Urchin  home  page 

(http://www.google.com/urchin/index.html)  and  click  the  Download 
link. 

2 Select  the  installer  that  most  closely  matches  your  platform.  The 
name  of  the  installer  includes  the  Urchin  version  and  the  operating 
system  type  (e.g.,  urchin41 00_redhat6x.sh). 

Note:  Currently,  only  versions  5.7.03  and  below  are  supported. 

If  necessary,  upload  the  installer  to  a temporary  location  on  the  system  where  you 
are  installing  Urchin.  If  you  are  not  on  the  console,  telnet  (or  use  ssh  if  available)  to 
the  system  and  cd  to  the  directory  where  the  installer  is  located. 

3 From  the  command  line,  type  the  name  of  the  installer.  For  example: 

. /urchin4100_redhat7x . sh 

This  unpacks  the  files  that  comprise  the  installation  kit. 

4 From  the  command  line,  execute  the  main  installation  script  by  typing: 

. / install . sh 

The  script  prompts  you  for  input  as  needed;  just  follow  the  instructions. 

5 Following  the  instructions  of  the  manual,  configure  Urchin  in  the 
directory  /hsphere/local/urchin. 

Note:  Urchin  port  and  owner  can  be  set  by  default  (9999,  nobody). 

6 Create  directory  /hsphere/local/urchin/var/logs  by  running: 
mkdir  /hsphere/ local/ urchin/var/logs 

7 Set  directory  owner  the  same  as  for  Urchin  on  step  5: 

chown  nobody : nobody  /hsphere/local/urchin/var/logs 

Important:  Make  steps  8-12  on  all  web  boxes. 

8 Check  httpd.conf  for  Script  Alias  directive  in  the  shared  IP  Virtual  Host 
(usually  /hsphere/ local/ sqwebmail  directory).  If  this  directory 
doesn't  exist  - create  it  with  755  permissions. 

9 Copy  print- log  . pi  script  from  the  /hsphere / shared/ script s 

directory: 

cp  /hsphere/ shared/ scripts/print-log . pi 
/hsphere/ local/ sqwebmail/ cgi-bin/ 

10  Set  755  permissions  for  this  script: 

chmod  755  /hsphere/local/sqwebmail/cgi-bin/print-log . pi 

11  Create  loglist  file: 
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touch  /hsphere/local/ sqwebmail/ cgi-bin/loglist 

12  Set  owner  and  group  for  this  file  to  httpd: 

chown  httpd: httpd  /hsphere/local/ sqwebmail/ cgi-bin/loglist 

13  In  the  hsphere . properties  file,  configure  the  following  variables: 

■ URCHINSERVERJD  = [URCHINSERVERID] 

ID  of  the  logical  server  where  Urchin  is  installed.  You  can  get  the  logical  server 
ID  in  E. Manager 

- URCHINPORT  = [URCHINPORT] 
the  port  taken  by  Urchin 

- URCHINSCHEDULERSTART  = [URCHINSCHEDULERSTART] 

■ URCHINSCHEDULERFINISH  = [SCHEDULERFINISH] 

the  hours  when  statistics  is  collected,  e.g,  2 and  4 means  statistics  will  be 
collected  between  2 and  4 AM 

■ URCHINPROTOCOL  = [URCHIN_PROTOCOL] 

the  protocol  to  connect  to  the  Urchin  control  panel,  can  be  http  or  https.  The 
default  is  http 

■ URCHIN_SERVERNAME  = [URCHIN_SERVERNAME] 

Urchin  server  URL,  should  be  set  in  addition  to  URCPIIN_SERVER_ID  on 
systems  with  NAT  support  (on  page  28)  (the  Urchin  server  in  this  case  has  a 
local  IP).  In  other  cases,  you  should  comment  out  or  skip  setting  this  parameter. 

14  Restart  Parallels  H-Sphere  (on  page  54)  for  changes  to  take  effect. 
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Urchin  4 and  5 Installation  on  Windows 

1 Install  Urchin  as  instructed  by  the  Urchin  Installation  Guide  (Windows) 
at 

http://www.qooqle.com/support/urchin45/bin/answer.py?answer=2854 

6&topic=7372. 

2 Log  in  to  Parallels  H-Sphere  control  panel  server  as  root. 

3 In  the  hsphere  . properties  file,  configure  the  following  variables: 

■ URCHIN_SERVER_ID  = <LSERVER_ID> 

ID  of  the  logical  server  where  Urchin4  is  installed 

■ URCHIN_PORT  = <SERVER_PORT> 
port  where  Urchin  is  installed 

■ URCHIN_SCHEDULER_START  = <SCHEDULER_START_HOUR> 

• URCHIN_SCHEDULER_FINISH  = <SCHEDULER_STOP_HOUR> 

the  hours  when  statistics  is  collected,  e.g.  between  2 and  4 

■ urchin_protocoL  = <PROTOCOL> 

the  protocol  to  connect  to  the  Urchin  control  panel,  e.g.,  http  or  https. 

4 Restart  HSphere  (on  page  54)  for  changes  to  take  effect. 
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Urchin  4 And  Urchin  5 Database  Utilities 


Urchin  Database  Utilities 

Urchin  4/5  installation  includes  utilities  to  insert,  edit,  and  delete  records  in  Urchin 
database.  The  only  two  ways  to  change  data  in  Urchin  internal  database  are  through 
Urchin  Control  Panel  or  by  the  means  of  Urchin  database  utilities. 

The  following  Urchin  database  utilities  are  located  in  the  util  subdirectory  of  the 
Urchin  installation  directory  (/hsphere/ shared/ urchin  for  Unix,  C : \Program 
Fiies\Urchin  for  Windows): 

■ uconf-import  (not  used  for  Parallels  H-Sphere  Windows  accounts)  is  a utility  that 
imports  XML  data  to  Urchin  database.  XML  data  may  be  transferred  to  the  standard 
input  or  taken  from  an  XML  file. 

For  more  details  on  uconf-import  options,  see  the  manual  on  the  Urchin 
Documentation  Center  at  http://help.urchin.com/index.cqi?id=1489 

■ uconf-driver  (uconf-driver.exe  for  Windows)  is  a utility  that  allows  inserting, 
deleting  or  updating  database  tables. 

Visit  Urchin  Documentation  Center  for  the  uconf-driver  options  at 
http://help.urchin.com/index.cqi?id=1 051 . 


Urchin  Database  Tables 

1 Logfile  is  the  table  that  holds  log  file  locations.  In  Parallels  H-Sphere,  Urchin  log 
files  are  accessed  remotely  via  HTTP  protocol.  Log  file  is  returned  by  the  print- 
log,  pi  script. 

Here  is  an  example  of  XML  representaion  of  a Logfile  table  record: 

CLogfile  Name="urchin . com"> 
ct  name=urchin . com 
cr  type=remote 

ct  1 oglocat i on=/hspher e/ local /ur chin /var/ logs/ 

cr_protocol=http 

ct  server=63 . 212 . 171 . 4 

ct_port=80 

ct  remotelocation=cgi-bin/print- 
log.pl?urchin&urchin. com&xgyvi jmuxpuad07plw/nuw==& . gz 


cs  logf ormat=ncsa 
</Logf ile> 

Field  description: 


Field  name 

XML  Representation 

Description 

Name 

<Logf ile 

Name="urchin . com 

Record  name,  coincides 
with  the  domain  name  in 
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"> 

Parallels  H-Sphere. 

ct  name 

ct  name=urchin . c 

om 

The  name  of  a domain 
where  statistics  is  collected. 

cr  type 

cr  type=remote 

Type  of  access  to  log  files;  it 
is  always  "remote"  in 

Parallels  H-Sphere 

ct  loglocati 

on 

ct  loglocation=/ 
hsphere/local/ur 
chi n/var/ logs/ 

On  remote  access  to  this 
directory,  log  files  with  Web 
boxes'  collected  statistics 
are  taken. 

cr  protocol 

cr  protocol=http 

Protocol  used  to  access  log 
files;  it  is  always  "http"  in 
Parallels  H-Sphere; 

ct  server 

ct  server=63 . 212 
. 171 . 4 

IP  of  the  logical  server 
where  log  files  are  located. 

ct  remoteloc 

ation 

ct  remotelocatio 
n=  cgi- 
bin/print- 
log.pl?urchin&ur 
chin . com&xgyvi jm 
uxpuad07plw/ nuw= 

= & . gz 

Location  of  log  files;  in 
Parallels  H-Sphere,  it  is  set 
as  the  URI  of  a CGI  script 
that  collects  statistics  from 
remote  log  files,  with  a query 
string  containing  the  script 
parameters. 

cs  logformat 

cs  logf ormat=ncs 

a 

Log  file  format:  ncsa  for 

Unix,  w3c  for  Windows. 

2 Profile  is  a table  used  to  access  statistics  in  the  form  of  charts,  diagrams,  etc. 


Here  is  an  example  of  XML  representation  of  a Profile  table  record: 

<Profile  Name="urchin . com"> 
ct  name=urchin . com 
ct  website=http : //urchin . com 
ct  reportdomains=urchin . com, www . urchin . com 
cs  llist="urchin . com" 

</Prof ile> 

Table  field  description: 


Field  name 

XML  Representation 

Description 

Name 

<Prof ile 

Name="urchin . corn'd 

Record  name,  coinsides 
with  the  domain  name  in 
Parallels  H-Sphere. 

ct  name 

ct  name=urchin . com 

The  name  of  a domain 
where  statistics  is  being 
collected. 

ct  website 

ct  website=http : // 
urchin . com 

Web  site  URL. 

ct  reportdo 
mains 

ct  reportdomains=u 
rchin . com, www . urch 
in . com 

Possible  ways  to  access 
domain,  domain  names 
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3 User  is  the  table  where  the  list  of  users  is  stored.  User  names  are  identical  to 
Parallels  H-Sphere  account  names.  Access  to  reports  is  also  set  in  this  table. 

Here  is  an  example  of  XML  representation  of  a Users  table  record: 

CUser  Name="Urchin"> 
ct  name=Urchin 
ct_password=USCC | 3980261512 
cs  rlist="urchin . com" 

</User> 


Table  field  description: 


Field  name 

XML  Representation 

Description 

Name 

CUser  Name="Urchin"> 

Record  name,  coincides 
with  the  domain  name  in 
Parallels  H-Sphere. 

ct  name 

ct  name=Urchin 

User  name. 

ct  passwo 
rd 

ct  password=USCC | 3980 
261512 

User's  password. 

cs  rlist 

cs  rlist="urchin . com" 

The  list  of  available 
reports. 

4 Task  is  the  table  that  contains  tasks  for  collecting  statistics. 


Here  is  an  example  of  XML  representation  of  a Task  table  record: 

CTask  Name="urchin . com"> 
ct  name=urchin . com 
cr  frequency=5 
cs  hour=4 
cs  minute=0 


</Task> 


Field  name 

XML  Representation 

Description 

Name 

CTask 

Name="urchin . corn'd 

Record  name,  coincides 
with  the  domain  name  in 
Parallels  H-Sphere. 

ct  name 

ct  name=urchin . com 

Domain  name. 

cr  frequ 
ency 

cr  frequency=5 

Task  launching  frequency; 

5 means  it  would  launch 
every  24  hours. 

cs  hour 

cs  minut 

e 

cs  hour=4, 
cs  minute=0 

Task  launching  time. 
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RealServer 

Parallels  H-Sphere  supports  all  versions  of  RealServer  that  have  ISPHosting  support.  If 
your  license  does  not  support  ISPHosting,  contact  your  RealServer  account 
representative  to  obtain  a license  key  that  has  the  same  number  of  streams  and 
properly  enables  ISP  hosting. 

In  this  chapter: 

RealServer  Installation  for  Unix 468 

RealServer  Installation  for  Windows 474 

RealServer  Config  File  Example 474 
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RealServer  Installation  for  Unix 


RealServer  can  be  installed  on  a web  box  or  a separate  box  with  apache. 

> To  install  RealServer  for  Unix: 

1 Install  RealServer  with  ISPHosting  support  on  a web  box  or  a 
separate  box  into  /hsphere/shared/RealServer  as  instructed  by 
RealServer  documentation  at 

http://www.realnetworks.com/products/server/.  If  you  set  it  up  on  a 
web  box,  specify  8080  port  instead  of  the  default  80,  which  is  used  by 
apache.  During  the  installation,  note  the  following  data,  as  you  will 
need  them  on  subsequent  steps: 

■ RealServer  IP 

■ RealServer  Admin  Port 

■ Administrator  Login 

■ Administrator  Password 

2 Add  the  following  line  to  the  RealServer  crontab: 

0 7 * * * nice  -15 

/hsphere/ shared/ scripts/ cron/rmserver  analyze .pi 

3 Launch  RealServer  with  the  following  command: 

/hsphere/shared/RealServer/Bin/rmserver  rmserver.cfg  & 

4 Log  into  your  RealServer  interface  using  administrator  login  and 
password.  To  get  there,  type  this  URL  in  address  field  of  your 
browser: 

http://RS  IP:ADMIN  PORT/admin/index . html 

replacing  rs_ip  and  admin_port  with  the  RealServer  IP  and  admin  port  you 
were  given  during  the  installation. 

5 In  the  left  menu,  select  Server  Setup  ->  Mount  Points. 

6 In  the  form  that  appears,  add  mount  point /shiva/  -> 

/hsphere/ local /home: 
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Server  Setup 

Ports 

IP  Binding 
MIME  Types 
Connection  Control 
Redundant 
Servers 
Mount  Points 
URL  Aliasing 
HTTP  Delivery 
Cache  Directives 
Shared  Licensing 
User/Group  Name 
Media  Samples 
Security 

Logging  & 
Monitoring 

Broadcasting 

Content 

Management 


point.  Its  default  base  path  is  the  Content 
subdirectory  under  your  server  isntallation  directory. 
Modify  the  base  path  of  the  main  "/"  mount  point 
only  if  the  base  path  does  not  reflect  the  location  of 
your  media  files. 


Mount  Points 


Pending  Changes 


HELP 


Mount  Point  Description  PB 

RNCache  Local  File  System 
RealSystem  Content 
RealSystem  Secure  Content 


shiva 


Edit  Description 
|shiva 

Mount  Point 

[/shiva/ 

Base  Path 

|/hsphere/loca  l/hon 

Base  Path  Location 

d 


Local 

Cacheable  by 

Caching 

Subscribers 

I yes  J 


J 

v 

*A  server  restart  is  required  to  effect  changes 
applied  to  this  page. 


Apply 


Restt 
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7 Click  Apply.  The  status  window  will  open: 


Helix  Administrator 


Configuration  Change  Results 

Property 

Action  Taken 

Status 

RealSystem  Secure 
Content 

UseContentDistribution 

Set  to  1 

Succeeded 

shiva 

BasePath 

Set  to 

/hsphere/loca  I/home 

Succeeded 

shiva 

ShortName 

Set  to  pn-local 

Succeeded 

shiva 

MountPoint 

Set  to  /shiva/ 

Succeeded 

shiva 

UseContentDistribution 

Set  to  1 

Succeeded 

RNCache  Local  File 
System 

Set  to  1 

Succeeded 

UseContentDistribution 


Close 


Close  this  window. 

8 Click  Restart  Server  in  the  upper  right  corner  of  the  browser  window 
to  restart  RealServer: 

Helix  Administrator 

Help  I Readme  | Tech  Support  | About 


RealServer  471 


9 Select  Content  Management  ->  ISP  Hosting  in  the  left  menu: 

Security 

Logging  & 

Monitoring 

Broadcasting 

Content 

Management 

Content  Caching 

ISP  Hosting 

Content  Browsing 
View  Source 

10  In  the  ISP  Hosting  form,  add  the  following  settings: 

Translation  Mounts:  user 

User  List  File  Name:  /hsphere/local/ conf  ig/RealServer/user . list 

Description:  users 
Mount  Point:  /shiva/ 

User  Path:  /shiva/ 
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+ ISP  Hosting 

Translation  Mounts 


users 


HELP 

DE3  Edit  Translation 
Mount  Description 
|users 

Mount  Point 

| /shiva/ 

Create  mount  point 
for  ISP  content. 


User  List  File  Names 


/hsphere/loca  1/confiq/RealServer/user.list 


_ User  Path 

[/shiva/ 

PE5  Edit  User  List  File 

Name 

[)nfig/RealServer/user 


*A  server  restart  is  required  to  effect  changes  applied  to  this  page. 


Apply  I Reset 


11  Click  Apply.  The  status  window  will  open: 
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* Helix  Administrator  - Change  Status  - Mozilla  {Build  ID:  0000000000)  - □ x 

Helix  Administrator 


Configuration  Change  Results 


Property 

Action  Taken 

Status 

ISPHosting.UserLists 

Removed 

Succeeded 

TranslationMounts 

users 

Set  to  /shiva/ 

Succeeded 

TranslationMounts 

users 

Set  to  /shiva/ 

Succeeded 

User  Lists 

File_l 

Set  to 

/hsphere/loca  1/config/RealServer/user.list 

Succeeded 

Close 


Close  this  window. 

12  Click  About  in  the  upper  left  corner  of  the  browser  window: 

Helix  Administrator 

Help  | Readme  | Tech  Support  | About 


I 

You  will  get  a window  with  information  about  your  license. 

13  Go  to  the  admin  control  panel  and  add  the  box  to  Parallels  H-Sphere 
as  suggested  in  Adding  Servers  Step-By-Step  of  the  Service 
Administrator  Guide. 

14  Now  you  can  proceed  to  RealServer  settings  that  are  not  related  to 
Parallels  H-Sphere. 

Here  is  an  example  of  RealServer  configuration  file: 
http://hsphere.parallels.com/HSdocumentation/sysadmin/rmserver.cfq.html. 
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RealServer  Installation  for  Windows 

> To  install  RealServer  for  Windows: 

1 Install  RealServer  with  ISPHosting  support 

2 Add  mount  point  /shiva/  ->  /user's_home_directory 

*You  can  learn  your  home  directory  in  the  conf . inc  file,  next  to  the  UserHome 
line. 

3 Restart  RealServer. 

4 After  that,  at  the  ISPHosting  page  in  the  Translation  Mounts  window: 

add  users  (Description:  users;  Mount  Point:  /shiva/;  User  Path:  /shiva/) 

add  user  list  (Edit  User  List  File  Name  in  the  directory  where  Parallels  H-Sphere  is 
installed:  /HSPhe re /Real Server/ user. list) 


RealServer  Config  File  Example 


< ! — SYSTEM  — > 

<Var  ProcessorCount="l"/> 

< ! — PATHS  — > 


<Var  LogPath="/var/hsphere/ rmserver/ rmaccess . log"/> 

<Var  ErrorLogPath=" / var/hsphere/ rmserver/ rmerror . log" /> 

<Var  PidPath="/ var/hsphere/ rmserver/ rmserver . pid" /> 

<Var  PluginDirectory=" /hsphere/ shared/RealServer/Plugins"/> 

<Var  SupportPluginDirectory=" /hsphere/ shared/ Real Server /Lib" / > 

<Var  LicenseDirectory=" /hsphere/ shared/RealServer/License"/> 

< ! — PORTS  — > 

<!--UNIX  customers  must  have  root  privileges  to  execute  the  server  --> 
<!--with  the  RTSP  port  set  to  554.  --> 

<!--The  following  are  the  default  ports  that  RealPlayer  and  --> 

<! --RealPlayer  Plus  clients  will  connect  to  for  an  URL  that  has  --> 
<!--no  port  specified:  -->  <!--  RTSP:  554  -->  <!--  PNM:  7070  --> 

<!--  HTTP:  80  (...then  8080  if  80  is  unavailable)  --> 

<Var  RTSPPort=" 554 "/> 

<Var  PNAPor t= " 7 0 7 0 " / > 

<Var  HTTPPort="8080"/> 

<Var  MonitorPort="9090"/> 

<Var  AdminPort="27781"/> 

< ! — PASSWORDS  — > 

<Var  MonitorPassword="123456"/> 

< ! — ALLOWANCE  — > 

<Var  ValidPlayersOnly="0"/> 

<Var  EnableCookieBasedIDs="0 "/> 

< ! — LOGGING  — > 


<Var  LoggingStyle="5"/>  <Var  StatsMask="3"/> 

< ! — LIVEARCHIVING  — > 

<List  Name="LiveArchive"> 

<List  Name="*"> 

<Var  Targe t Direct or y=" /Archive/ " / > 
<Var  BandwidthNegotiation="0 "/> 
<Var  FileSize="0"/> 
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<Var  FileTime="OmOhOd"/> 

<Var  NoArchive=" 0 " /> 

</List> 

</List> 

< ! — HTTPSUPPORT  — > 

<List  Name="HTTPDeliverable"> 

<Var  Path_0=" /admin" /> 

<Var  Path  1=" /ramgen" /> 

<Var  Path  2="/farm"/> 

<Var  Path_3="/httpfs"/> 

<Var  Path  4="/viewsource"/> 

</List> 

<!--  <Var  Path_0=" /scalable" />  --> 

< ! — MIMETYPES  — > 

<List  Name="MimeTypes"> 

<List  Name="text/html"> 

<Var  Ext_l="html"/> 

<Var  Ext_2="htm" /> 

</List> 

<List  Name=" audio/ x-pn-realaudio"> 

<Var  Ext_l="ram"/> 

</List> 

<List  Name="image/gif "> 

<Var  Ext_l="gif "/> 

</List> 

<List  Name="image/ jpg"> 

<Var  Ext_l=" jpg"/> 

<Var  Ext_2=" jpeg"/> 

</List> 

</List> 

< ! — AUTHENTICATION  — > 

<List  Name= " Au then ticationRea lms "> 

<List  Name="SecureAdmin"> 

<Var  Realm="ultra . shiva . AdminRealm" /> 
<List  Name="BasicAuthenticator"> 

<Var  Plugin I D="rn-auth-basic" / > 
<Var  DatabaseID="Admin  Basic"/> 
</List> 

</List> 

<List  Name="SecureEncoder"> 

<Var  Realm="ultra . shiva . EncoderRealm" / > 
<List  Name="RN5Authenticator"> 

<Var  PluginID="rn-auth-rn5"/> 

<Var  Database I D="Encoder^RN5" / > 
</List> 

</List> 

<List  Name="SecureContent"> 

<Var  Realm=" ultra . shiva . ContentRealm" / > 
<List  Name="RN5Authenticator"> 

<Var  PluginID="rn-auth-rn5"/> 

<Var  DatabaseID="Content  RN5"/> 
</List> 

</List> 

</List> 

< ! — COMMERCE  — > 

<List  Name="CommerceRules"> 

<List  Name="SecureUserContent"> 

<Var  ProtectedVirtualPath=" / secure"/> 
<Var  Realm=" ultra . shiva . ContentRealm" /> 
<!--  <Var  UseGUIDValidation="True"/  --> 
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<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="Content  RN5"/> 

<!--  <Var  AllowDuplicateIDs="True"/  --> 

</List> 

<List  Name="SecureG2LiveContent"> 

<Var  ProtectedVirtualPath=" / encoder/ secure" / > 

<Var  Realm=" ultra . shiva . ContentRealm" / > 

<!--  <Var  UseGUIDValidation="True"/  --> 

<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="Content  RN5"/> 

<!--  <Var  AllowDuplicateIDs="True"/  --> 

</List> 

<List  Name="SecurePreG2LiveContent"> 

<Var  ProtectedVirtualPath=" /live/ secure" / > 

<Var  Realm=" ultra . shiva . ContentRealm" / > 

<!--  <Var  UseGUIDValidation="True"/  --> 

<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID="Content  RN5"/> 

<!--  <Var  AllowDuplicateIDs="True"/  --> 

</List> 

<List  Name="SecurePlayerContent"> 

<Var  ProtectedVirtualPath=" / secure/player"/> 

<Var  UseGUIDValidation="0"/> 

<Var  EvaluatePermissions="0"/> 

<Var  DatabaseID=" PlayerContent" / > 

<!--  <Var  AllowDuplicateIDs="True"/  --> 

</List> 

</List> 

<List  Name="GUIDRegistrationPref ixes"> 

<List  Name=" PlayerContentRegistration"> 

<Var  GUIDRegistrationPref ix=" register" /> 

<Var  DatabaseID=" PlayerContent" / > 

</List> 

</List> 

< ! — DATABAS  E S — > 

<List  Name="Databases"> 

<List  Name="Admin  Basic"> 

<Var  Plugin I D="rn-db- flat file" / > 

<Var  Path=" /hsphere/shared/RealServer/adm  b db"/> 
</List> 

<List  Name="Encoder_RN5"> 

<Var  Plugin I D="rn-db- flat file" / > 

<Var  Path=" /hsphere/shared/RealServer/enc_r  db"/> 
</List> 

<List  Name="Content_RN5"> 

<Var  Plugin I D="rn-db-f latf ile"/> 

<Var  Path=" /hsphere/shared/RealServer/con_r  db"/> 
</List> 

<List  Name=" PlayerContent"> 

<Var  Plugin I D="rn-db-f latf ile"/> 

<Var  Path=" /hsphere/shared/RealServer/con_p  db"/> 
</List> 

</List> 

< ! — VIEWSOURCE  — > 

<List  Name="ViewSourceConf iguration"> 

<Var  ViewSourceLongName="View  Source  Tag  FileSystem" /> 
<List  Name="/"> 

<Var  AllowViewSource=" 1 " /> 

<Var  HidePaths="l"/> 

</List> 
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</List> 

< ! — CONTENTBROWSINIG  — > 

<List  Name="ContentBrowsing"> 

<List  Name="BrowsableMountPoints"> 

<Var  Mount_l="/"/> 

<Var  Mount_2=" /shiva/ " /> 

</List> 

<List  Name="IndexExtensions"> 

<Var  Ext_l— " * "/> 

</List> 

</List> 

< ! — FILESYSTEMS  — > 

__> 

<List  Name="FSMount"> 

<!--  Local  File  System;  Media  --> 

<List  Name="RealSystem  Content"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint="/"/> 

<Var  BasePath="/hsphere/ shared/ Real Server/ Content" /> 
</List> 

<!--  Local  File  System;  Secure  Media  --> 

<List  Name="RealSystem  Secure  Content"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint=" /secure/ " /> 

<Var  BasePath=" /hsphere/ shared/ Real Server/ Secure" / > 
</List> 

<!--  Local  File  System;  HTML  --> 

<List  Name="RealSystem  Administrator  HTML"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint=" / admin/html/"/> 

<Var 

BasePath=" /hsphere/ shared /Real Server /RealAdministrator" / > 

</List> 

<!--  Local  File  System;  DOCS  --> 

<List  Name="RealSystem  Administrator  DOCS"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint=" / admin/Docs/"/> 

<Var 

BasePath=" /hsphere/ shared/RealServer/RealAdministrator/Docs"/> 

</List> 

<!--  Local  File  System;  IMAGES  --> 

<List  Name="RealSystem  Administrator  IMAGES"> 

<Var  ShortName="pn-local"/>  <Var 
MountPoint=" / admin/ images/"/> 

<Var 

BasePath=" /hsphere/ shared /Real Server /RealAdministrator/ images" / > 
</List> 

< ! — Local  File  System;  JAVAMONITOR  — > 

<List  Name="RealSystem  Administrator  JAVAMONITOR"> 

<Var  ShortName="pn-local"/> 

<Var  MountPoint=" / admin/ JavaMonitor/ " / > 

<Var 

BasePath=" /hsphere/ shared /Real Server /RealAdministrator/ JavaMonitor" / > 
</List> 

<!--  XML  Tag  Handler  File  System  --> 

<List  Name="Real  System  Administrator  SSI"> 

<Var  ShortName="pn-xmltag" /> 

<Var  MountPoint=" / admin/ includes/"/> 

<Var  BaseMountPoint=" / admin/html/ "/> 

<List  Name="TagHandlers"> 
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<Var  hl="pn-includer" /> 

<Var  h2="pn-vsrctaghdlr"/> 

</List> 

</List> 

<!--  Admin  File  System  --> 

<List  Name="RealSystem  Administrator  Files"> 

<Var  ShortName="pn-admin" /> 

<Var  MountPoint="/admin/"/> 

<Var  BaseMountPoint=" / admin/ includes/ " / > 

<Var  Realm="ultra . shiva . AdminRealm" /> 

</List> 

<!--  Splitter  Broadcast  --> 

<List  Name="Splitter_DoubleURL"> 

<Var  ShortName="pn-splitter"/> 

<Var  MountPoint="/split/"/> 

<Var  Port="3030"/> 

</List> 

<!--  G2  Encoders  --> 

<List  Name="RealSystem  G2  Encoders'^ 

<Var  ShortName="pn-encoder" /> 

<Var  MountPoint=" /encoder/ " /> 

<Var  Port="4040"/> 

<Var  EncoderRealm=" ultra . shiva . EncoderRealm" / > 
</List> 

<!--  Pre-G2  Encoders  --> 

<List  Name=" Pre-RealSystem  G2  Encoders'^ 

<Var  ShortName="pn-live3"/> 

<Var  MountPoint=" /live/ " /> 

<Var  Port="5050"/> 

<!--  Var  Password="123456"/  --> 

</List> 

<!--  RAM  File  Generator  --> 

<List  Name="RAM  File  Generator"> 

<Var  ShortName="pn-ramgen"/> 

<Var  MountPoint=" /ramgen/ " /> 

</List> 

<!--  View  Source  File  system  --> 

<List  Name="View  Source  File  System"> 

<Var  ShortName="pn-vsrcfsys"/> 

<Var  MountPoint="/vsrcf sys/"/> 

</List> 

<!--  View  Source  Tag  File  System;  Source  Insertion  --> 

<List  Name="View  Source  Tag  FileSystem"> 

<Var  ShortName="pn-xmltag"/> 

<Var  Moun tPo in t=" /views our ce/ "/> 

<Var  BaseMountPoint=" /vsrcf sys/ " /> 

<List  Name="TagHandlers"> 

<List  Name="ViewSource  Tag  Handler"> 

<Var  ShortName="pn-vsrctaghdlr"/> 
</List> 

</List> 

</List> 

<!--  General  Ad  Insertion  --> 

<List  Name="General  Ad  Insertion"> 

<Var  ShortName="pn-xmltag" /> 

<Var  MountPoint=" / adtag/ general/ " / > 

<Var  BaseMountPoint=" / " /> 

<List  Name="TagHandlers"> 

<List  Name="Ad  Tag  Replacement  Plugin"> 
<Var  ShortName="rn-adtaghandler"/> 
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<Var  AdRetrievalMountPoint=" /httpf s/ " / > 
<Var  AdPlaybackMountPoint=" /httpf s/ "/> 
<Var 

AdURL="http : / / www . real . com/ ads/ g2ads  def . html"/> 

<Var  Rotate="0"/>  <Var  Bitrate="4000"/> 
<Var  Interval="30"/>  <Var 
RotationMountPoint=" /shellfs/"/> 

</List> 

</List> 

</List> 

<!--  Banner  Ad  SMIL  Generation  --> 

<List  Name="Banner  Ad  SMIL  Generation"> 

<Var  ShortName="pn-smilgen" /> 

<Var  MountPoint=" / smilgen/banner/"/> 

<Var  BaseMountPoint=" / " /> 

<Var  Layout="AdBottom" /> 

<Var  OuterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor="black"/> 

<Var  AdType="Banner" /> 

<Var  EnablePlaylist=" 0 " /> 

<Var  AdWidth="468"/> 

<Var  AdHeight=" 60 " /> 

</List> 

<!--  Lead-in  Ad  SMIL  Generation  --> 

<List  Name="Lead-in  Ad  SMIL  Generation"> 

<Var  ShortName="pn-smilgen" /> 

<Var  MountPoint=" / smilgen/leadin/"/> 

<Var  BaseMountPoint=" / " /> 

<Var  Layout="AdCenter" /> 

<Var  OuterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor="black" /> 

<Var  AdType="Leadin"/> 

<Var  EnablePlaylist=" 0 " /> 

<Var  AdWidth="468"/> 

<Var  AdHeight=" 60 " /> 

</List> 

<!--  Continuous  Rotating  Banner  Ad  SMIL  Generation  --> 

<List  Name="Continuous  Rotating  Banner  Ad  SMIL  Generation"> 

<Var  ShortName="pn-smilgen" /> 

<Var  MountPoint=" / smilgen/ rbanner/ " / > 

<Var  BaseMountPoint=" / " /> 

<Var  Layout="AdBottom"/> 

<Var  OuterPadding="5"/> 

<Var  InnerPadding="5"/> 

<Var  BGColor="black" /> 

<Var  AdType="RotatingBanner" /> 

<Var  EnablePlaylist=" 0 " /> 

<Var  AdWidth="468"/> 

<Var  AdHeight=" 60 " /> 

</List> 

<!--  HTTP  File  System  --> 

<List  Name="HTTP  File  System"> 

<Var  ShortName="pn-http" /> 

<Var  MountPoint=" /httpf s/ " /> 

<Var  ConnectionTimeout="10"/> 

<Var  ServerTimeout="10"/> 

<Var  MangleCookies="0"/> 

</List> 
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<!--  RealSystem  Shell  File  System  --> 

<List  Name="RealSystem  Shell  File  System"> 

<Var  ShortName="pn-shell"/> 

<Var  MountPoint="/shellfs/"/> 

<Var  AdRetrievalMountPoint=" /httpf s/ " / > 

<Var  AdPl aybackMountPo in t=" /httpf s/ " / > 

</List> 

<List  Name="Users"> 

<Var  MountPoint="/shiva/"/> 

<Var  Ba se Pa th=" /hsphere/ local/ real /home/ "/> 

<Var  ShortName="pn-local"/> 

</List> 

</List> 

< ! — CACHING  — > 

<Var  TSPort="7802"/> 

<Var  TSEnable="l"/> 

<Var  TSLog="l"/> 

<Var  TSLogPath=" /hsphere/ shared/RealServer/Logs/ cache . log"/> 

< ! — MULTICAST  — > 

<List  Name="Multicast"> 

<List  Name="ControlList"> 

<List  Name="100"> 

<Var  Allow="Any" /> 

</List> 

</List> 

<Var  RTSPPort="554 " / > 

<Var  PNAPort="7070 "/> 

<Var  DeliveryOnly="0"/> 

<Var  Resend="l"/> 

<Var  TTL="16"/> 

</List> 

<List  Name= "MediaExport Interface "> 

<Var  LogFile=" /hsphere/ shared/RealServer/Logs/ cache . log"/> 
<Var  LoggingEnabled="l"/> 

<Var  TransferSize="2048"/> 

<Var  Enabled="l"/> 

<Var  ListenPort="7878"/> 

<Var  ChainingID="007b4603"/> 

<Var  Tracemask="OxO"/> 

<Var  LogFormat="MEIl"/> 

<Var  Timeout="120"/> 

</List> 

<Var  CloakingHint=" 1 " /> 

<Var  Capacity="10000"/> 

<Var  PlusOnly="0"/> 

<Var  MaxBandwidth=" 0 " /> 

<Var  User="%-l"/> 

<Var  RTSPMessageDebug="0"/> 

<Var  LiveFileBandwidthNegotiation="0 "/> 

<Var  MonitorConnections="4"/> 

<Var  Group="%-l"/> 

<Var  MinPlayerProtocol="0"/> 

<Var  ClientConnections="0"/> 

<List  Name="ISPHosting"> 

<List  Name="TranslationMounts"> 

<List  Name="users"> 

<Var  UserPath=" /shiva/ " /> 

<Var  MountPoint=" /shiva/ " /> 

</List> 

</List> 
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<List  Name="UserLists"> 

<Var  File_2=" /hsphere/ local/ con fig /Real Server/ user. list "/> 
</List> 

</List> 


